diff --git a/v1.3.1/404.html b/v1.3.1/404.html new file mode 100644 index 000000000..7e328f5e7 --- /dev/null +++ b/v1.3.1/404.html @@ -0,0 +1,3317 @@ + + + + + + + + + + + + + + + + + + + Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ +

404 - Not found

+ +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/SUMMARY/index.html b/v1.3.1/SUMMARY/index.html new file mode 100644 index 000000000..8555948f0 --- /dev/null +++ b/v1.3.1/SUMMARY/index.html @@ -0,0 +1,3394 @@ + + + + + + + + + + + + + + + + + + + SUMMARY - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

SUMMARY

+ + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/architecture/blockchain_connector_framework/index.html b/v1.3.1/architecture/blockchain_connector_framework/index.html new file mode 100644 index 000000000..fc6dec0f4 --- /dev/null +++ b/v1.3.1/architecture/blockchain_connector_framework/index.html @@ -0,0 +1,3786 @@ + + + + + + + + + + + + + + + + + + + + + + + Blockchain Connector Toolkit - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Blockchain Connector Toolkit

+ + +

Blockchain Connector Framework

+

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.

+

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.

+
+

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.

+
+

Connector Toolkit Architecture

+

FireFly Blockchain Connector Toolkit Architecture

+

The core component of the FireFly Connector Framework for Blockchains is a Go module +called FireFly Transaction Manager (FFTM).

+

FFTM is responsible for:

+
    +
  • +

    Submission of transactions to blockchains of all types

    +
    • +
  • +

    Protocol connectivity decoupled with additional lightweight API connector

    +
    • +
  • +

    Easy to add additional protocols that conform to normal patterns of TX submission / events

    +
    • +
  • +

    Monitoring and updating blockchain operations

    +
    • +
  • +

    Receipts

    +
    • +
  • +

    Confirmations

    +
    • +
  • +

    Extensible transaction handler with capabilities such as:

    +
    • +
  • +

    Nonce management: idempotent submission of transactions, and assignment of nonces

    +
    • +
  • Transaction management: pre-signing transactions, resubmission, customizable policy engine
    • +
  • Gas management: Gas Gas station API integration
    • +
  • +

    Transaction process history

    +
    • +
  • +

    Event streaming

    +
    • +
  • Protocol agnostic event polling/streaming support
    • +
  • Reliable checkpoint restart
    • +
  • At least once delivery API
    • +
+

Assumptions / Requirements

+

The framework is currently constrained to blockchains that adhere to certain basic principals:

+
    +
  1. +

    Has transactions

    +
    2. +
  2. +

    That are signed

    +
    3. +
  3. +

    That can optionally have gas semantics (limits and prices, expressed in a blockchain specific way)

    +
    4. +
  4. +

    Has events (or "logs")

    +
    5. +
  5. +

    That are emitted as a deterministic outcome of transactions

    +
    6. +
  6. +

    Has blocks

    +
    7. +
  7. +

    Containing zero or more transactions, with their associated events

    +
    8. +
  8. With a sequential numeric order
    9. +
  9. With a hash
    10. +
  10. +

    With a parent hash

    +
    11. +
  11. +

    Has finality for transactions & events that can be expressed as a level of confidence over time

    +
    12. +
  12. +

    Confirmations: A number of sequential blocks in the canonical chain that contain the transaction

    +
    13. +
+

Nonce management in the simple transaction handler

+

The nonces for transactions is assigned as early as possible in the flow:

+
    +
  • Before the REST API for submission of the transaction occurs
    • +
  • After the FFCAPI blockchain connector verifies the transaction can be encoded successfully to the chain
    • +
  • With protection against multiple parallel API requests for the same signing address
    • +
  • With stateful persistence meaning the connector knows about all nonces it previously allocated, to avoids duplicates
    • +
+

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.

+

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.

+

Avoid multiple nonce management systems against the same signing key

+

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.

+
+

Be careful that the signing keys for transactions you stream through the Nonce Management of the FireFly +blockchain connector are not used elsewhere.

+
+

If you must have multiple systems performing nonce management against the same keys you use with FireFly nonce management, +you can set the transactions.nonceStateTimeout to 0 (or a low threshold like 100ms) to cause the nonce management +to query the pending transaction pool of the node every time a nonce is allocated.

+

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.

+

Why "at source" nonce management was chosen vs. "at target"

+

The "at source" approach to ordering used in FFTM could be compared with the "at target" allocation of nonces used in +EthConnect).

+

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.

+

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.

+

However, "at target" comes with two compromises that mean FFTM chose the "at source" approach was chosen for FFTM:

+
    +
  • +

    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.

    +
    • +
  • +

    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.

    +
    • +
+

Transaction Handler

+

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.

+

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.

+

A reference implementation is provided that:

+
    +
  • Submits transactions via the underlying FFCAPI
    • +
  • Estimates gas price in one of three modes:
    • +
  • Fixed: It is specified via configuration
    • +
  • Connector: The FFCAPI is used to estimate the gas price (e.g. eth_gasPrice for EVM JSON/RPC)
    • +
  • Gas Oracle: A REST API is called the the result mapped via a Go template
    • +
  • Re-submits transactions after a configurable stale time
    • +
  • Record detailed information about transaction sub-status and actions
    • +
  • Emit customized metrics for transaction processing
    • +
+

The reference implementation is available here

+

Event Streams

+

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.

+

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.

+

Some high architectural principals that informed the code:

+
    +
  • Event Stream
    • +
  • A delivery stream of events that have been confirmed
    • +
  • Only events that have reached finality are delivered to an event stream
    • +
  • FireFly creates a single event stream per namespace from core
    • +
  • Each token connector creates a single event stream
    • +
  • If one event stream is blocked, it must not block other streams in the FFTM based runtime
    • +
  • Listener (/Subscription)
    • +
  • A blockchain specific specification for a set of events to listen to
    • +
  • Specifies an initial block to listen from, and will replay all events from that block
    • +
  • Can have multiple blockchain specific filters, to match multiple events
    • +
  • The order of delivery within a listener matches the blockchain across all filters + > - Note that the EVMConnect implementation of FFCAPI attempts to make this true across all listeners + > on an event stream. However, this is impossible when a new listener has been added, + > and that listener is catching up from an old block.
    • +
  • Compatibility
    • +
  • Has breaking changes from the API of EthConnect
    • +
  • A component that has been upgraded to support EVMConnect, + can maintain backwards compatibility with EthConnect
    • +
  • Batching & Checkpoints
    • +
  • Delivery on event streams is via batches, with a single confirmation for each batch
    • +
  • At-least-once delivery of batches
    • +
  • Checkpoints are written after each batch
    • +
  • Chain head stability
    • +
  • A configurable section of the head of the chain is considered unstable
    • +
  • If no events have been delivered for a listener, checkpoints are still moved forwards
    • +
  • These empty checkpoints will never be written in the unstable head of the chain
    • +
  • Confirmation manager
    • +
  • Plugged in between detection of the events, and assembling into batches
    • +
  • Determines the final order based on order of confirmation on the blockchain
    • +
+

FireFly Connector Toolkit Event Streams

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/architecture/internal_event_sequencing/index.html b/v1.3.1/architecture/internal_event_sequencing/index.html new file mode 100644 index 000000000..61639039b --- /dev/null +++ b/v1.3.1/architecture/internal_event_sequencing/index.html @@ -0,0 +1,3629 @@ + + + + + + + + + + + + + + + + + + + + + + + Internal Event Sequencing - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Internal Event Sequencing

+ + +

Overview

+

Internal Event Sequencing

+

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.

+

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

+

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:

+
    +
  • Private messaging in the Data Exchange
    • +
  • The blockchain ledger(s) themselves, which are a stream of sequenced events
    • +
  • The event dispatcher delivering messages to applications that have been sequenced by FireFly
    • +
+

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.

+

The sequence is made deterministic:

+
    +
  • Globally to all apps within the scope of the ledger, when a Blockchain ledger is used to pin events (see #10)
    • +
  • Locally for messages delivered through a single FireFly node into the network
    • +
  • Locally for all messages delivered to applications connected to a FireFly node, across blockchain
    • +
+

App Instances

+
    +
  • Broadcast messages to the network
    • +
  • Ingest ack when message persisted in local messages table
    • +
  • Consume events via Websocket connection into FireFly
    • +
+

Outbound Sequencers

+
    +
  • Broadcast or Private through IPFS or Private Data Storage
    • +
  • Long-running leader-elected jobs listening to the database (via event tables in SQL, etc.)
    • +
+

Inbound Aggregator

+
    +
  • Triggered each time an event is detected by the associated plugin.
    • +
  • It is the responsibility of the plugin to fire events sequentially. Can be workload managed but must be sequential.
    • +
+

Events Table

+
    +
  • Deliberately lightweight persisted object, that is generated as a byproduct of other persistent actions.
    • +
  • Records the local sequence of a specific event within the local node.
    • +
  • The highest level event type is the confirmation of a message, however the table can be extended for more granularity on event types.
    • +
+

Subscription Manager

+
    +
  • Responsible for filtering and delivering batches of events to the active event dispatchers.
    • +
  • Records the latest offset confirmed by each dispatcher.
    • +
+

Event Dispatcher

+
    +
  • Created with leadership election when WebSocket connection is made from an app into FireFly.
    • +
  • Extensible to other dispatchers (AMQP, etc.).
    • +
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/architecture/multiparty_event_sequencing/index.html b/v1.3.1/architecture/multiparty_event_sequencing/index.html new file mode 100644 index 000000000..aa080e304 --- /dev/null +++ b/v1.3.1/architecture/multiparty_event_sequencing/index.html @@ -0,0 +1,3538 @@ + + + + + + + + + + + + + + + + + + + + + + + Multiparty Event Sequencing - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Multiparty Event Sequencing

+ + +

Multiparty Event Sequencing

+

Transaction Submission

+
    +
  • An individual FireFly instance preserves the order that it received messages from application instances.
    • +
  • Where possible, batching is used to roll-up hundreds of transactions into a single blockchain transaction.
    • +
  • Blockchain allows these messages to be globally sequenced with messages submitted by other members of the network.
    • +
+

Blockchain Ordering

+
    +
  • All member FireFly runtimes see every transaction in the same sequence.
    • +
  • This includes when transactions are being submitted by both sides concurrently.
    • +
+

Message Assembly

+
    +
  • A queue of events is maintained for each matching app subscription.
    • +
  • The public/private payloads travel separately to the blockchain, and arrive at different times. FireFly assembles these together prior to delivery.
    • +
  • If data associated with a blockchain transaction is late, or does not arrive, all messages on the same "context" will be blocked.
    • +
  • 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.
    • +
+

Event Processing

+
    +
  • Events are processed consistently by all parties.
    • +
  • All FireFly runtimes see every event that they are subscribed to, in the same sequence.
    • +
  • 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.
    • +
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/architecture/node_component_architecture/index.html b/v1.3.1/architecture/node_component_architecture/index.html new file mode 100644 index 000000000..0a1550cba --- /dev/null +++ b/v1.3.1/architecture/node_component_architecture/index.html @@ -0,0 +1,3558 @@ + + + + + + + + + + + + + + + + + + + + + + + Node Component Architecture - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Node Component Architecture

+ + +

What is a FireFly Node?

+

The core architecture of a FireFly node can be broken down into the following three areas:

+
    +
  • The various runtimes encapsulating the node.
    • +
  • The core runtime responsibilities and pluggable elements.
    • +
  • The actual code running inside the node.
    • +
+

FireFly Architecture Overview

+

Runtimes

+

What fundamentally is a node - left side of the above diagram.

+
    +
  • It is a collection of multiple runtimes with a single unified HTTPS/Websocket API (exposed by the Core).
    • +
  • It has a private database, containing your private data, and data received from others in the network.
    • +
  • It has connectivity out to other parties in the network, through runtimes (Blockchain, Shared Filesystems, Messaging etc.).
    • +
+

Responsibilities & Pluggable Elements

+

What are the core runtime responsibilities, and pluggable elements - right side of the above diagram.

+
    +
  • The core elements of function that FireFly performs, and which runtime is responsible.
    • +
  • This means some insight into core itself, and the jobs it performs, but not full code structure.
    • +
  • More importantly, what the split of responsibilities is between Connectors and Infrastructure Runtimes.
      +
    • Connectors are the bridging runtimes, that know how to talk to a particular runtime.
      • +
    • They run separately to the core (like a microservice architecture of an app).
      • +
    • They can be written in any language (not just Go) - Java, TypeScript, Rust, Python, .NET etc.
      • +
    • They can use any network transport (not just HTTPS/Websockets) - GRPC, AMQP, UDP etc.
      • +
    • They connect to the core with a Golang shim - see separate Plugin Architecture discussion. + > - In some special cases (like the Database) the Golang shim does not need a connector runtime.
      • +
    • Infrastructure Runtimes are the core runtimes for multi-party system activities.
      • +
    • Blockchain nodes - Ethereum (Hyperledger Besu, Quorum, Geth), Hyperledger Fabric, Corda etc.
      • +
    • Shared strorage - IPFS etc.
      • +
    • Database - PostreSQL, CouchDB etc.
      • +
    +
    • +
+

Code Structure

+

What is the code structure inside the core.

+
    +
  • The README.md is the reference for this.
    • +
  • Developers contributing to FireFly, on the core, or building new plugins, need this level of detail.
    +
      +
    • A reconciliation is underway to ensure the medium-level view correlates well with this code structure.
      • +
    +
    +
    • +
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/architecture/ping_pong_txflow/index.html b/v1.3.1/architecture/ping_pong_txflow/index.html new file mode 100644 index 000000000..130692ccd --- /dev/null +++ b/v1.3.1/architecture/ping_pong_txflow/index.html @@ -0,0 +1,3588 @@ + + + + + + + + + + + + + + + + + + + + + + + Example Transaction Flow - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Example Transaction Flow (Ping Pong)

+ + +

Overview

+

Simple Ping Pong Tx Flow

+

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.

+
    +
  • Party A: Establish existence of a digital asset.
    • +
  • Nothing more than some binary data (an image, a document, a specification etc.).
    • +
  • Party A: Broadcast some information about that asset to everyone, using blockchain to record, sequence and propagate.
    • +
  • So people can find it, or part of a more sophisticated workflow.
    • +
  • Party B: Request the actual data - with evidence of that request tied to the blockchain.
    • +
  • Including some private data that's sent to the Party A, reliably off-chain.
    • +
  • Party A: Authorize the request, and send the data privately to Party B.
    • +
  • In this example there's no blockchain involved in this step.
    • +
+

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.

+

The "tramlines" view shows how FireFly's pluggable model makes the job of the developer really simple:

+
    +
  • A few simple API calls from a modern web app.
    • +
  • Event triggered execution of application logic.
    • +
+

This is deliberately a simple flow, and all kinds of additional layers might well layer on (and fit within the FireFly model):

+
    +
  • NFTs to track ownership etc. related to the digital asset.
    • +
  • Tokenized rewards/payments integrated with the authorization of the transfer of data.
    • +
  • Proof of deterministic execution of the logic to perform the authorization (on-chain, TEEs, ZKPs).
    • +
  • Human workflow, that is of course completely non-deterministic.
    • +
  • Multiple additional process steps, deterministic or not.
    • +
  • Inclusion of multiple additional parties (maybe it's a request-for-tender, submit-tender flow for example).
    • +
  • etc.
    • +
+

Broadcast Public Description of Binary Data Asset (Member 1)

+
    +
  • Upload Blob of the actual data
    • +
  • Returns a hash of the payload
    • +
  • Upload JSON containing the public index data
    • +
  • Includes the hash of the full payload
    • +
  • Send a broadcast message with the public index data
    • +
  • Agree upon a primary key of the data as the "context"
    • +
+

Receive Public Description & Request Asset Data (Member 2)

+
    +
  • Store data in your own off-chain database for rich, efficient query
    • +
  • Run automated logic to decide if you want to request the full data
    • +
  • Upload JSON for data request
    • +
  • Send a private message
    • +
  • Backed by blockchain in this flow
    • +
+

Authorize & Transfer Data (Member 1)

+
    +
  • Inspect the request data
    • +
  • Retrieve data asset by hash
    • +
  • Send the private data in a private message
    • +
  • No blockchain in this flow
    • +
+

Receive Data Asset (Member 2)

+
    +
  • Receive a link to your local copy of the asset data
    • +
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/architecture/plugin_architecture/index.html b/v1.3.1/architecture/plugin_architecture/index.html new file mode 100644 index 000000000..65c3c12ca --- /dev/null +++ b/v1.3.1/architecture/plugin_architecture/index.html @@ -0,0 +1,3602 @@ + + + + + + + + + + + + + + + + + + + + + + + Plugin Architecture - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Plugin Architecture

+ + +
+

FireFly Plugin Architecture +This diagram shows the various plugins that are currently in the codebase and the layers in each plugin

+
+

FireFly Plugin Architecture +This diagram shows the details of what goes into each layer of a FireFly plugin

+
+

Overview

+

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:

+

This architecture is designed to provide separations of concerns to account for:

+
    +
  • Differences in code language for the low-level connection to a backend (Java for Corda for example)
    • +
  • Differences in transports, particularly for delivery of events:
    • +
  • Between FireFly Core and the Connector
      +
    • Different transports other than HTTPS/WebSockets (GRPC etc.), and different wire protocols (socket.io, etc.)
      • +
    +
    • +
  • Between the Connector and the underlying Infrastructure Runtime
      +
    • Often this is heavy lifting engineering within the connector
      • +
    +
    • +
  • Differences in High Availability (HA) / Scale architectures
    • +
  • Between FireFly Core, and the Connector
      +
    • Often for event management, and active/passive connector runtime is sufficient
      • +
    +
    • +
  • Between the Connector and the Infrastructure Runtime
      +
    • 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
      • +
    +
    • +
+

FireFly Core

+
    +
  • Golang
    • +
  • N-way scalable cluster
    • +
  • Database is also pluggable via this architecture
    • +
  • No long lived in-memory processing
    • +
  • All micro-batching must be recoverable
    • +
  • Driven by single configuration set
    • +
  • Viper semantics - file, env var, cmdline flags
    • +
+

Plugin for Connector

+
    +
  • Golang
    • +
  • Statically compiled in support at runtime
    • +
  • Go dynamic plugin support too immature
    • +
  • Must be 100% FLOSS code (no GPL/LGPL etc.)
    • +
  • Contributed via PR to FF Core
    • +
  • Intended to be lightweight binding/mapping
    • +
  • Must adhere to FF Core Coding Standards
    • +
  • Scrutiny on addition of new frameworks/transports
    • +
+

Connector

+
    +
  • Node.js / Java / Golang, etc.
    • +
  • Runs/scales independently from FF core
    • +
  • Coded in any language, OSS or proprietary
    • +
  • One runtime or multiple
    • +
  • HA model can be active/passive or active/active
    • +
  • Expectation is all plugins need a connector
    • +
  • Some exceptions exist (e.g. database plugin)
    • +
+

Infrastructure Runtime

+
    +
  • Besu, Quorum, Corda, Fabric, IPFS, Kafka, etc.
    • +
  • Runs/scales independently from FF Core
    • +
  • Coded in any language, OSS or proprietary
    • +
  • Not specific to FireFly
    • +
  • HA model can be active/passive or active/active
    • +
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/assets/FireFly-Logo.svg b/v1.3.1/assets/FireFly-Logo.svg new file mode 100644 index 000000000..395e207f4 --- /dev/null +++ b/v1.3.1/assets/FireFly-Logo.svg @@ -0,0 +1,142 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v1.3.1/assets/FireFly_Logo_White.svg b/v1.3.1/assets/FireFly_Logo_White.svg new file mode 100644 index 000000000..9b8776e1f --- /dev/null +++ b/v1.3.1/assets/FireFly_Logo_White.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/v1.3.1/assets/favicon.ico b/v1.3.1/assets/favicon.ico new file mode 100644 index 000000000..fd5bc16ee Binary files /dev/null and b/v1.3.1/assets/favicon.ico differ diff --git a/v1.3.1/assets/images/favicon.png b/v1.3.1/assets/images/favicon.png new file mode 100644 index 000000000..1cf13b9f9 Binary files /dev/null and b/v1.3.1/assets/images/favicon.png differ diff --git a/v1.3.1/assets/javascripts/bundle.fe8b6f2b.min.js b/v1.3.1/assets/javascripts/bundle.fe8b6f2b.min.js new file mode 100644 index 000000000..cf778d428 --- /dev/null +++ b/v1.3.1/assets/javascripts/bundle.fe8b6f2b.min.js @@ -0,0 +1,29 @@ +"use strict";(()=>{var Fi=Object.create;var gr=Object.defineProperty;var ji=Object.getOwnPropertyDescriptor;var Wi=Object.getOwnPropertyNames,Dt=Object.getOwnPropertySymbols,Ui=Object.getPrototypeOf,xr=Object.prototype.hasOwnProperty,no=Object.prototype.propertyIsEnumerable;var oo=(e,t,r)=>t in e?gr(e,t,{enumerable:!0,configurable:!0,writable:!0,value:r}):e[t]=r,R=(e,t)=>{for(var r in t||(t={}))xr.call(t,r)&&oo(e,r,t[r]);if(Dt)for(var r of Dt(t))no.call(t,r)&&oo(e,r,t[r]);return e};var io=(e,t)=>{var r={};for(var o in e)xr.call(e,o)&&t.indexOf(o)<0&&(r[o]=e[o]);if(e!=null&&Dt)for(var o of Dt(e))t.indexOf(o)<0&&no.call(e,o)&&(r[o]=e[o]);return r};var yr=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var Di=(e,t,r,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of Wi(t))!xr.call(e,n)&&n!==r&&gr(e,n,{get:()=>t[n],enumerable:!(o=ji(t,n))||o.enumerable});return e};var Vt=(e,t,r)=>(r=e!=null?Fi(Ui(e)):{},Di(t||!e||!e.__esModule?gr(r,"default",{value:e,enumerable:!0}):r,e));var ao=(e,t,r)=>new Promise((o,n)=>{var i=p=>{try{s(r.next(p))}catch(c){n(c)}},a=p=>{try{s(r.throw(p))}catch(c){n(c)}},s=p=>p.done?o(p.value):Promise.resolve(p.value).then(i,a);s((r=r.apply(e,t)).next())});var co=yr((Er,so)=>{(function(e,t){typeof Er=="object"&&typeof so!="undefined"?t():typeof define=="function"&&define.amd?define(t):t()})(Er,function(){"use strict";function e(r){var o=!0,n=!1,i=null,a={text:!0,search:!0,url:!0,tel:!0,email:!0,password:!0,number:!0,date:!0,month:!0,week:!0,time:!0,datetime:!0,"datetime-local":!0};function s(H){return!!(H&&H!==document&&H.nodeName!=="HTML"&&H.nodeName!=="BODY"&&"classList"in H&&"contains"in H.classList)}function p(H){var mt=H.type,ze=H.tagName;return!!(ze==="INPUT"&&a[mt]&&!H.readOnly||ze==="TEXTAREA"&&!H.readOnly||H.isContentEditable)}function c(H){H.classList.contains("focus-visible")||(H.classList.add("focus-visible"),H.setAttribute("data-focus-visible-added",""))}function l(H){H.hasAttribute("data-focus-visible-added")&&(H.classList.remove("focus-visible"),H.removeAttribute("data-focus-visible-added"))}function f(H){H.metaKey||H.altKey||H.ctrlKey||(s(r.activeElement)&&c(r.activeElement),o=!0)}function u(H){o=!1}function h(H){s(H.target)&&(o||p(H.target))&&c(H.target)}function w(H){s(H.target)&&(H.target.classList.contains("focus-visible")||H.target.hasAttribute("data-focus-visible-added"))&&(n=!0,window.clearTimeout(i),i=window.setTimeout(function(){n=!1},100),l(H.target))}function A(H){document.visibilityState==="hidden"&&(n&&(o=!0),te())}function te(){document.addEventListener("mousemove",J),document.addEventListener("mousedown",J),document.addEventListener("mouseup",J),document.addEventListener("pointermove",J),document.addEventListener("pointerdown",J),document.addEventListener("pointerup",J),document.addEventListener("touchmove",J),document.addEventListener("touchstart",J),document.addEventListener("touchend",J)}function ie(){document.removeEventListener("mousemove",J),document.removeEventListener("mousedown",J),document.removeEventListener("mouseup",J),document.removeEventListener("pointermove",J),document.removeEventListener("pointerdown",J),document.removeEventListener("pointerup",J),document.removeEventListener("touchmove",J),document.removeEventListener("touchstart",J),document.removeEventListener("touchend",J)}function J(H){H.target.nodeName&&H.target.nodeName.toLowerCase()==="html"||(o=!1,ie())}document.addEventListener("keydown",f,!0),document.addEventListener("mousedown",u,!0),document.addEventListener("pointerdown",u,!0),document.addEventListener("touchstart",u,!0),document.addEventListener("visibilitychange",A,!0),te(),r.addEventListener("focus",h,!0),r.addEventListener("blur",w,!0),r.nodeType===Node.DOCUMENT_FRAGMENT_NODE&&r.host?r.host.setAttribute("data-js-focus-visible",""):r.nodeType===Node.DOCUMENT_NODE&&(document.documentElement.classList.add("js-focus-visible"),document.documentElement.setAttribute("data-js-focus-visible",""))}if(typeof window!="undefined"&&typeof document!="undefined"){window.applyFocusVisiblePolyfill=e;var t;try{t=new CustomEvent("focus-visible-polyfill-ready")}catch(r){t=document.createEvent("CustomEvent"),t.initCustomEvent("focus-visible-polyfill-ready",!1,!1,{})}window.dispatchEvent(t)}typeof document!="undefined"&&e(document)})});var Yr=yr((Rt,Kr)=>{/*! + * clipboard.js v2.0.11 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */(function(t,r){typeof Rt=="object"&&typeof Kr=="object"?Kr.exports=r():typeof define=="function"&&define.amd?define([],r):typeof Rt=="object"?Rt.ClipboardJS=r():t.ClipboardJS=r()})(Rt,function(){return function(){var e={686:function(o,n,i){"use strict";i.d(n,{default:function(){return Ii}});var a=i(279),s=i.n(a),p=i(370),c=i.n(p),l=i(817),f=i.n(l);function u(V){try{return document.execCommand(V)}catch(_){return!1}}var h=function(_){var M=f()(_);return u("cut"),M},w=h;function A(V){var _=document.documentElement.getAttribute("dir")==="rtl",M=document.createElement("textarea");M.style.fontSize="12pt",M.style.border="0",M.style.padding="0",M.style.margin="0",M.style.position="absolute",M.style[_?"right":"left"]="-9999px";var j=window.pageYOffset||document.documentElement.scrollTop;return M.style.top="".concat(j,"px"),M.setAttribute("readonly",""),M.value=V,M}var te=function(_,M){var j=A(_);M.container.appendChild(j);var D=f()(j);return u("copy"),j.remove(),D},ie=function(_){var M=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body},j="";return typeof _=="string"?j=te(_,M):_ instanceof HTMLInputElement&&!["text","search","url","tel","password"].includes(_==null?void 0:_.type)?j=te(_.value,M):(j=f()(_),u("copy")),j},J=ie;function H(V){"@babel/helpers - typeof";return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?H=function(M){return typeof M}:H=function(M){return M&&typeof Symbol=="function"&&M.constructor===Symbol&&M!==Symbol.prototype?"symbol":typeof M},H(V)}var mt=function(){var _=arguments.length>0&&arguments[0]!==void 0?arguments[0]:{},M=_.action,j=M===void 0?"copy":M,D=_.container,Y=_.target,ke=_.text;if(j!=="copy"&&j!=="cut")throw new Error('Invalid "action" value, use either "copy" or "cut"');if(Y!==void 0)if(Y&&H(Y)==="object"&&Y.nodeType===1){if(j==="copy"&&Y.hasAttribute("disabled"))throw new Error('Invalid "target" attribute. Please use "readonly" instead of "disabled" attribute');if(j==="cut"&&(Y.hasAttribute("readonly")||Y.hasAttribute("disabled")))throw new Error(`Invalid "target" attribute. You can't cut text from elements with "readonly" or "disabled" attributes`)}else throw new Error('Invalid "target" value, use a valid Element');if(ke)return J(ke,{container:D});if(Y)return j==="cut"?w(Y):J(Y,{container:D})},ze=mt;function Ie(V){"@babel/helpers - typeof";return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?Ie=function(M){return typeof M}:Ie=function(M){return M&&typeof Symbol=="function"&&M.constructor===Symbol&&M!==Symbol.prototype?"symbol":typeof M},Ie(V)}function _i(V,_){if(!(V instanceof _))throw new TypeError("Cannot call a class as a function")}function ro(V,_){for(var M=0;M<_.length;M++){var j=_[M];j.enumerable=j.enumerable||!1,j.configurable=!0,"value"in j&&(j.writable=!0),Object.defineProperty(V,j.key,j)}}function Ai(V,_,M){return _&&ro(V.prototype,_),M&&ro(V,M),V}function Ci(V,_){if(typeof _!="function"&&_!==null)throw new TypeError("Super expression must either be null or a function");V.prototype=Object.create(_&&_.prototype,{constructor:{value:V,writable:!0,configurable:!0}}),_&&br(V,_)}function br(V,_){return br=Object.setPrototypeOf||function(j,D){return j.__proto__=D,j},br(V,_)}function Hi(V){var _=Pi();return function(){var j=Wt(V),D;if(_){var Y=Wt(this).constructor;D=Reflect.construct(j,arguments,Y)}else D=j.apply(this,arguments);return ki(this,D)}}function ki(V,_){return _&&(Ie(_)==="object"||typeof _=="function")?_:$i(V)}function $i(V){if(V===void 0)throw new ReferenceError("this hasn't been initialised - super() hasn't been called");return V}function Pi(){if(typeof Reflect=="undefined"||!Reflect.construct||Reflect.construct.sham)return!1;if(typeof Proxy=="function")return!0;try{return Date.prototype.toString.call(Reflect.construct(Date,[],function(){})),!0}catch(V){return!1}}function Wt(V){return Wt=Object.setPrototypeOf?Object.getPrototypeOf:function(M){return M.__proto__||Object.getPrototypeOf(M)},Wt(V)}function vr(V,_){var M="data-clipboard-".concat(V);if(_.hasAttribute(M))return _.getAttribute(M)}var Ri=function(V){Ci(M,V);var _=Hi(M);function M(j,D){var Y;return _i(this,M),Y=_.call(this),Y.resolveOptions(D),Y.listenClick(j),Y}return Ai(M,[{key:"resolveOptions",value:function(){var D=arguments.length>0&&arguments[0]!==void 0?arguments[0]:{};this.action=typeof D.action=="function"?D.action:this.defaultAction,this.target=typeof D.target=="function"?D.target:this.defaultTarget,this.text=typeof D.text=="function"?D.text:this.defaultText,this.container=Ie(D.container)==="object"?D.container:document.body}},{key:"listenClick",value:function(D){var Y=this;this.listener=c()(D,"click",function(ke){return Y.onClick(ke)})}},{key:"onClick",value:function(D){var Y=D.delegateTarget||D.currentTarget,ke=this.action(Y)||"copy",Ut=ze({action:ke,container:this.container,target:this.target(Y),text:this.text(Y)});this.emit(Ut?"success":"error",{action:ke,text:Ut,trigger:Y,clearSelection:function(){Y&&Y.focus(),window.getSelection().removeAllRanges()}})}},{key:"defaultAction",value:function(D){return vr("action",D)}},{key:"defaultTarget",value:function(D){var Y=vr("target",D);if(Y)return document.querySelector(Y)}},{key:"defaultText",value:function(D){return vr("text",D)}},{key:"destroy",value:function(){this.listener.destroy()}}],[{key:"copy",value:function(D){var Y=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body};return J(D,Y)}},{key:"cut",value:function(D){return w(D)}},{key:"isSupported",value:function(){var D=arguments.length>0&&arguments[0]!==void 0?arguments[0]:["copy","cut"],Y=typeof D=="string"?[D]:D,ke=!!document.queryCommandSupported;return Y.forEach(function(Ut){ke=ke&&!!document.queryCommandSupported(Ut)}),ke}}]),M}(s()),Ii=Ri},828:function(o){var n=9;if(typeof Element!="undefined"&&!Element.prototype.matches){var i=Element.prototype;i.matches=i.matchesSelector||i.mozMatchesSelector||i.msMatchesSelector||i.oMatchesSelector||i.webkitMatchesSelector}function a(s,p){for(;s&&s.nodeType!==n;){if(typeof s.matches=="function"&&s.matches(p))return s;s=s.parentNode}}o.exports=a},438:function(o,n,i){var a=i(828);function s(l,f,u,h,w){var A=c.apply(this,arguments);return l.addEventListener(u,A,w),{destroy:function(){l.removeEventListener(u,A,w)}}}function p(l,f,u,h,w){return typeof l.addEventListener=="function"?s.apply(null,arguments):typeof u=="function"?s.bind(null,document).apply(null,arguments):(typeof l=="string"&&(l=document.querySelectorAll(l)),Array.prototype.map.call(l,function(A){return s(A,f,u,h,w)}))}function c(l,f,u,h){return function(w){w.delegateTarget=a(w.target,f),w.delegateTarget&&h.call(l,w)}}o.exports=p},879:function(o,n){n.node=function(i){return i!==void 0&&i instanceof HTMLElement&&i.nodeType===1},n.nodeList=function(i){var a=Object.prototype.toString.call(i);return i!==void 0&&(a==="[object NodeList]"||a==="[object HTMLCollection]")&&"length"in i&&(i.length===0||n.node(i[0]))},n.string=function(i){return typeof i=="string"||i instanceof String},n.fn=function(i){var a=Object.prototype.toString.call(i);return a==="[object Function]"}},370:function(o,n,i){var a=i(879),s=i(438);function p(u,h,w){if(!u&&!h&&!w)throw new Error("Missing required arguments");if(!a.string(h))throw new TypeError("Second argument must be a String");if(!a.fn(w))throw new TypeError("Third argument must be a Function");if(a.node(u))return c(u,h,w);if(a.nodeList(u))return l(u,h,w);if(a.string(u))return f(u,h,w);throw new TypeError("First argument must be a String, HTMLElement, HTMLCollection, or NodeList")}function c(u,h,w){return u.addEventListener(h,w),{destroy:function(){u.removeEventListener(h,w)}}}function l(u,h,w){return Array.prototype.forEach.call(u,function(A){A.addEventListener(h,w)}),{destroy:function(){Array.prototype.forEach.call(u,function(A){A.removeEventListener(h,w)})}}}function f(u,h,w){return s(document.body,u,h,w)}o.exports=p},817:function(o){function n(i){var a;if(i.nodeName==="SELECT")i.focus(),a=i.value;else if(i.nodeName==="INPUT"||i.nodeName==="TEXTAREA"){var s=i.hasAttribute("readonly");s||i.setAttribute("readonly",""),i.select(),i.setSelectionRange(0,i.value.length),s||i.removeAttribute("readonly"),a=i.value}else{i.hasAttribute("contenteditable")&&i.focus();var p=window.getSelection(),c=document.createRange();c.selectNodeContents(i),p.removeAllRanges(),p.addRange(c),a=p.toString()}return a}o.exports=n},279:function(o){function n(){}n.prototype={on:function(i,a,s){var p=this.e||(this.e={});return(p[i]||(p[i]=[])).push({fn:a,ctx:s}),this},once:function(i,a,s){var p=this;function c(){p.off(i,c),a.apply(s,arguments)}return c._=a,this.on(i,c,s)},emit:function(i){var a=[].slice.call(arguments,1),s=((this.e||(this.e={}))[i]||[]).slice(),p=0,c=s.length;for(p;p{"use strict";/*! + * escape-html + * Copyright(c) 2012-2013 TJ Holowaychuk + * Copyright(c) 2015 Andreas Lubbe + * Copyright(c) 2015 Tiancheng "Timothy" Gu + * MIT Licensed + */var ts=/["'&<>]/;ei.exports=rs;function rs(e){var t=""+e,r=ts.exec(t);if(!r)return t;var o,n="",i=0,a=0;for(i=r.index;i0&&i[i.length-1])&&(c[0]===6||c[0]===2)){r=0;continue}if(c[0]===3&&(!i||c[1]>i[0]&&c[1]=e.length&&(e=void 0),{value:e&&e[o++],done:!e}}};throw new TypeError(t?"Object is not iterable.":"Symbol.iterator is not defined.")}function N(e,t){var r=typeof Symbol=="function"&&e[Symbol.iterator];if(!r)return e;var o=r.call(e),n,i=[],a;try{for(;(t===void 0||t-- >0)&&!(n=o.next()).done;)i.push(n.value)}catch(s){a={error:s}}finally{try{n&&!n.done&&(r=o.return)&&r.call(o)}finally{if(a)throw a.error}}return i}function q(e,t,r){if(r||arguments.length===2)for(var o=0,n=t.length,i;o1||s(u,h)})})}function s(u,h){try{p(o[u](h))}catch(w){f(i[0][3],w)}}function p(u){u.value instanceof nt?Promise.resolve(u.value.v).then(c,l):f(i[0][2],u)}function c(u){s("next",u)}function l(u){s("throw",u)}function f(u,h){u(h),i.shift(),i.length&&s(i[0][0],i[0][1])}}function mo(e){if(!Symbol.asyncIterator)throw new TypeError("Symbol.asyncIterator is not defined.");var t=e[Symbol.asyncIterator],r;return t?t.call(e):(e=typeof de=="function"?de(e):e[Symbol.iterator](),r={},o("next"),o("throw"),o("return"),r[Symbol.asyncIterator]=function(){return this},r);function o(i){r[i]=e[i]&&function(a){return new Promise(function(s,p){a=e[i](a),n(s,p,a.done,a.value)})}}function n(i,a,s,p){Promise.resolve(p).then(function(c){i({value:c,done:s})},a)}}function k(e){return typeof e=="function"}function ft(e){var t=function(o){Error.call(o),o.stack=new Error().stack},r=e(t);return r.prototype=Object.create(Error.prototype),r.prototype.constructor=r,r}var zt=ft(function(e){return function(r){e(this),this.message=r?r.length+` errors occurred during unsubscription: +`+r.map(function(o,n){return n+1+") "+o.toString()}).join(` + `):"",this.name="UnsubscriptionError",this.errors=r}});function qe(e,t){if(e){var r=e.indexOf(t);0<=r&&e.splice(r,1)}}var Fe=function(){function e(t){this.initialTeardown=t,this.closed=!1,this._parentage=null,this._finalizers=null}return e.prototype.unsubscribe=function(){var t,r,o,n,i;if(!this.closed){this.closed=!0;var a=this._parentage;if(a)if(this._parentage=null,Array.isArray(a))try{for(var s=de(a),p=s.next();!p.done;p=s.next()){var c=p.value;c.remove(this)}}catch(A){t={error:A}}finally{try{p&&!p.done&&(r=s.return)&&r.call(s)}finally{if(t)throw t.error}}else a.remove(this);var l=this.initialTeardown;if(k(l))try{l()}catch(A){i=A instanceof zt?A.errors:[A]}var f=this._finalizers;if(f){this._finalizers=null;try{for(var u=de(f),h=u.next();!h.done;h=u.next()){var w=h.value;try{fo(w)}catch(A){i=i!=null?i:[],A instanceof zt?i=q(q([],N(i)),N(A.errors)):i.push(A)}}}catch(A){o={error:A}}finally{try{h&&!h.done&&(n=u.return)&&n.call(u)}finally{if(o)throw o.error}}}if(i)throw new zt(i)}},e.prototype.add=function(t){var r;if(t&&t!==this)if(this.closed)fo(t);else{if(t instanceof e){if(t.closed||t._hasParent(this))return;t._addParent(this)}(this._finalizers=(r=this._finalizers)!==null&&r!==void 0?r:[]).push(t)}},e.prototype._hasParent=function(t){var r=this._parentage;return r===t||Array.isArray(r)&&r.includes(t)},e.prototype._addParent=function(t){var r=this._parentage;this._parentage=Array.isArray(r)?(r.push(t),r):r?[r,t]:t},e.prototype._removeParent=function(t){var r=this._parentage;r===t?this._parentage=null:Array.isArray(r)&&qe(r,t)},e.prototype.remove=function(t){var r=this._finalizers;r&&qe(r,t),t instanceof e&&t._removeParent(this)},e.EMPTY=function(){var t=new e;return t.closed=!0,t}(),e}();var Tr=Fe.EMPTY;function qt(e){return e instanceof Fe||e&&"closed"in e&&k(e.remove)&&k(e.add)&&k(e.unsubscribe)}function fo(e){k(e)?e():e.unsubscribe()}var $e={onUnhandledError:null,onStoppedNotification:null,Promise:void 0,useDeprecatedSynchronousErrorHandling:!1,useDeprecatedNextContext:!1};var ut={setTimeout:function(e,t){for(var r=[],o=2;o0},enumerable:!1,configurable:!0}),t.prototype._trySubscribe=function(r){return this._throwIfClosed(),e.prototype._trySubscribe.call(this,r)},t.prototype._subscribe=function(r){return this._throwIfClosed(),this._checkFinalizedStatuses(r),this._innerSubscribe(r)},t.prototype._innerSubscribe=function(r){var o=this,n=this,i=n.hasError,a=n.isStopped,s=n.observers;return i||a?Tr:(this.currentObservers=null,s.push(r),new Fe(function(){o.currentObservers=null,qe(s,r)}))},t.prototype._checkFinalizedStatuses=function(r){var o=this,n=o.hasError,i=o.thrownError,a=o.isStopped;n?r.error(i):a&&r.complete()},t.prototype.asObservable=function(){var r=new F;return r.source=this,r},t.create=function(r,o){return new Eo(r,o)},t}(F);var Eo=function(e){re(t,e);function t(r,o){var n=e.call(this)||this;return n.destination=r,n.source=o,n}return t.prototype.next=function(r){var o,n;(n=(o=this.destination)===null||o===void 0?void 0:o.next)===null||n===void 0||n.call(o,r)},t.prototype.error=function(r){var o,n;(n=(o=this.destination)===null||o===void 0?void 0:o.error)===null||n===void 0||n.call(o,r)},t.prototype.complete=function(){var r,o;(o=(r=this.destination)===null||r===void 0?void 0:r.complete)===null||o===void 0||o.call(r)},t.prototype._subscribe=function(r){var o,n;return(n=(o=this.source)===null||o===void 0?void 0:o.subscribe(r))!==null&&n!==void 0?n:Tr},t}(g);var _r=function(e){re(t,e);function t(r){var o=e.call(this)||this;return o._value=r,o}return Object.defineProperty(t.prototype,"value",{get:function(){return this.getValue()},enumerable:!1,configurable:!0}),t.prototype._subscribe=function(r){var o=e.prototype._subscribe.call(this,r);return!o.closed&&r.next(this._value),o},t.prototype.getValue=function(){var r=this,o=r.hasError,n=r.thrownError,i=r._value;if(o)throw n;return this._throwIfClosed(),i},t.prototype.next=function(r){e.prototype.next.call(this,this._value=r)},t}(g);var Lt={now:function(){return(Lt.delegate||Date).now()},delegate:void 0};var _t=function(e){re(t,e);function t(r,o,n){r===void 0&&(r=1/0),o===void 0&&(o=1/0),n===void 0&&(n=Lt);var i=e.call(this)||this;return i._bufferSize=r,i._windowTime=o,i._timestampProvider=n,i._buffer=[],i._infiniteTimeWindow=!0,i._infiniteTimeWindow=o===1/0,i._bufferSize=Math.max(1,r),i._windowTime=Math.max(1,o),i}return t.prototype.next=function(r){var o=this,n=o.isStopped,i=o._buffer,a=o._infiniteTimeWindow,s=o._timestampProvider,p=o._windowTime;n||(i.push(r),!a&&i.push(s.now()+p)),this._trimBuffer(),e.prototype.next.call(this,r)},t.prototype._subscribe=function(r){this._throwIfClosed(),this._trimBuffer();for(var o=this._innerSubscribe(r),n=this,i=n._infiniteTimeWindow,a=n._buffer,s=a.slice(),p=0;p0?e.prototype.schedule.call(this,r,o):(this.delay=o,this.state=r,this.scheduler.flush(this),this)},t.prototype.execute=function(r,o){return o>0||this.closed?e.prototype.execute.call(this,r,o):this._execute(r,o)},t.prototype.requestAsyncId=function(r,o,n){return n===void 0&&(n=0),n!=null&&n>0||n==null&&this.delay>0?e.prototype.requestAsyncId.call(this,r,o,n):(r.flush(this),0)},t}(vt);var So=function(e){re(t,e);function t(){return e!==null&&e.apply(this,arguments)||this}return t}(gt);var Hr=new So(To);var Oo=function(e){re(t,e);function t(r,o){var n=e.call(this,r,o)||this;return n.scheduler=r,n.work=o,n}return t.prototype.requestAsyncId=function(r,o,n){return n===void 0&&(n=0),n!==null&&n>0?e.prototype.requestAsyncId.call(this,r,o,n):(r.actions.push(this),r._scheduled||(r._scheduled=bt.requestAnimationFrame(function(){return r.flush(void 0)})))},t.prototype.recycleAsyncId=function(r,o,n){var i;if(n===void 0&&(n=0),n!=null?n>0:this.delay>0)return e.prototype.recycleAsyncId.call(this,r,o,n);var a=r.actions;o!=null&&((i=a[a.length-1])===null||i===void 0?void 0:i.id)!==o&&(bt.cancelAnimationFrame(o),r._scheduled=void 0)},t}(vt);var Mo=function(e){re(t,e);function t(){return e!==null&&e.apply(this,arguments)||this}return t.prototype.flush=function(r){this._active=!0;var o=this._scheduled;this._scheduled=void 0;var n=this.actions,i;r=r||n.shift();do if(i=r.execute(r.state,r.delay))break;while((r=n[0])&&r.id===o&&n.shift());if(this._active=!1,i){for(;(r=n[0])&&r.id===o&&n.shift();)r.unsubscribe();throw i}},t}(gt);var me=new Mo(Oo);var O=new F(function(e){return e.complete()});function Yt(e){return e&&k(e.schedule)}function kr(e){return e[e.length-1]}function Xe(e){return k(kr(e))?e.pop():void 0}function He(e){return Yt(kr(e))?e.pop():void 0}function Bt(e,t){return typeof kr(e)=="number"?e.pop():t}var xt=function(e){return e&&typeof e.length=="number"&&typeof e!="function"};function Gt(e){return k(e==null?void 0:e.then)}function Jt(e){return k(e[ht])}function Xt(e){return Symbol.asyncIterator&&k(e==null?void 0:e[Symbol.asyncIterator])}function Zt(e){return new TypeError("You provided "+(e!==null&&typeof e=="object"?"an invalid object":"'"+e+"'")+" where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.")}function Gi(){return typeof Symbol!="function"||!Symbol.iterator?"@@iterator":Symbol.iterator}var er=Gi();function tr(e){return k(e==null?void 0:e[er])}function rr(e){return lo(this,arguments,function(){var r,o,n,i;return Nt(this,function(a){switch(a.label){case 0:r=e.getReader(),a.label=1;case 1:a.trys.push([1,,9,10]),a.label=2;case 2:return[4,nt(r.read())];case 3:return o=a.sent(),n=o.value,i=o.done,i?[4,nt(void 0)]:[3,5];case 4:return[2,a.sent()];case 5:return[4,nt(n)];case 6:return[4,a.sent()];case 7:return a.sent(),[3,2];case 8:return[3,10];case 9:return r.releaseLock(),[7];case 10:return[2]}})})}function or(e){return k(e==null?void 0:e.getReader)}function W(e){if(e instanceof F)return e;if(e!=null){if(Jt(e))return Ji(e);if(xt(e))return Xi(e);if(Gt(e))return Zi(e);if(Xt(e))return Lo(e);if(tr(e))return ea(e);if(or(e))return ta(e)}throw Zt(e)}function Ji(e){return new F(function(t){var r=e[ht]();if(k(r.subscribe))return r.subscribe(t);throw new TypeError("Provided object does not correctly implement Symbol.observable")})}function Xi(e){return new F(function(t){for(var r=0;r=2;return function(o){return o.pipe(e?b(function(n,i){return e(n,i,o)}):le,Te(1),r?Be(t):zo(function(){return new ir}))}}function Fr(e){return e<=0?function(){return O}:y(function(t,r){var o=[];t.subscribe(T(r,function(n){o.push(n),e=2,!0))}function pe(e){e===void 0&&(e={});var t=e.connector,r=t===void 0?function(){return new g}:t,o=e.resetOnError,n=o===void 0?!0:o,i=e.resetOnComplete,a=i===void 0?!0:i,s=e.resetOnRefCountZero,p=s===void 0?!0:s;return function(c){var l,f,u,h=0,w=!1,A=!1,te=function(){f==null||f.unsubscribe(),f=void 0},ie=function(){te(),l=u=void 0,w=A=!1},J=function(){var H=l;ie(),H==null||H.unsubscribe()};return y(function(H,mt){h++,!A&&!w&&te();var ze=u=u!=null?u:r();mt.add(function(){h--,h===0&&!A&&!w&&(f=Wr(J,p))}),ze.subscribe(mt),!l&&h>0&&(l=new at({next:function(Ie){return ze.next(Ie)},error:function(Ie){A=!0,te(),f=Wr(ie,n,Ie),ze.error(Ie)},complete:function(){w=!0,te(),f=Wr(ie,a),ze.complete()}}),W(H).subscribe(l))})(c)}}function Wr(e,t){for(var r=[],o=2;oe.next(document)),e}function $(e,t=document){return Array.from(t.querySelectorAll(e))}function P(e,t=document){let r=fe(e,t);if(typeof r=="undefined")throw new ReferenceError(`Missing element: expected "${e}" to be present`);return r}function fe(e,t=document){return t.querySelector(e)||void 0}function Re(){var e,t,r,o;return(o=(r=(t=(e=document.activeElement)==null?void 0:e.shadowRoot)==null?void 0:t.activeElement)!=null?r:document.activeElement)!=null?o:void 0}var xa=S(d(document.body,"focusin"),d(document.body,"focusout")).pipe(_e(1),Q(void 0),m(()=>Re()||document.body),G(1));function et(e){return xa.pipe(m(t=>e.contains(t)),K())}function kt(e,t){return C(()=>S(d(e,"mouseenter").pipe(m(()=>!0)),d(e,"mouseleave").pipe(m(()=>!1))).pipe(t?Ht(r=>Me(+!r*t)):le,Q(e.matches(":hover"))))}function Bo(e,t){if(typeof t=="string"||typeof t=="number")e.innerHTML+=t.toString();else if(t instanceof Node)e.appendChild(t);else if(Array.isArray(t))for(let r of t)Bo(e,r)}function x(e,t,...r){let o=document.createElement(e);if(t)for(let n of Object.keys(t))typeof t[n]!="undefined"&&(typeof t[n]!="boolean"?o.setAttribute(n,t[n]):o.setAttribute(n,""));for(let n of r)Bo(o,n);return o}function sr(e){if(e>999){let t=+((e-950)%1e3>99);return`${((e+1e-6)/1e3).toFixed(t)}k`}else return e.toString()}function wt(e){let t=x("script",{src:e});return C(()=>(document.head.appendChild(t),S(d(t,"load"),d(t,"error").pipe(v(()=>$r(()=>new ReferenceError(`Invalid script: ${e}`))))).pipe(m(()=>{}),L(()=>document.head.removeChild(t)),Te(1))))}var Go=new g,ya=C(()=>typeof ResizeObserver=="undefined"?wt("https://unpkg.com/resize-observer-polyfill"):I(void 0)).pipe(m(()=>new ResizeObserver(e=>e.forEach(t=>Go.next(t)))),v(e=>S(Ke,I(e)).pipe(L(()=>e.disconnect()))),G(1));function ce(e){return{width:e.offsetWidth,height:e.offsetHeight}}function ge(e){let t=e;for(;t.clientWidth===0&&t.parentElement;)t=t.parentElement;return ya.pipe(E(r=>r.observe(t)),v(r=>Go.pipe(b(o=>o.target===t),L(()=>r.unobserve(t)))),m(()=>ce(e)),Q(ce(e)))}function Tt(e){return{width:e.scrollWidth,height:e.scrollHeight}}function cr(e){let t=e.parentElement;for(;t&&(e.scrollWidth<=t.scrollWidth&&e.scrollHeight<=t.scrollHeight);)t=(e=t).parentElement;return t?e:void 0}function Jo(e){let t=[],r=e.parentElement;for(;r;)(e.clientWidth>r.clientWidth||e.clientHeight>r.clientHeight)&&t.push(r),r=(e=r).parentElement;return t.length===0&&t.push(document.documentElement),t}function Ue(e){return{x:e.offsetLeft,y:e.offsetTop}}function Xo(e){let t=e.getBoundingClientRect();return{x:t.x+window.scrollX,y:t.y+window.scrollY}}function Zo(e){return S(d(window,"load"),d(window,"resize")).pipe(Le(0,me),m(()=>Ue(e)),Q(Ue(e)))}function pr(e){return{x:e.scrollLeft,y:e.scrollTop}}function De(e){return S(d(e,"scroll"),d(window,"scroll"),d(window,"resize")).pipe(Le(0,me),m(()=>pr(e)),Q(pr(e)))}var en=new g,Ea=C(()=>I(new IntersectionObserver(e=>{for(let t of e)en.next(t)},{threshold:0}))).pipe(v(e=>S(Ke,I(e)).pipe(L(()=>e.disconnect()))),G(1));function tt(e){return Ea.pipe(E(t=>t.observe(e)),v(t=>en.pipe(b(({target:r})=>r===e),L(()=>t.unobserve(e)),m(({isIntersecting:r})=>r))))}function tn(e,t=16){return De(e).pipe(m(({y:r})=>{let o=ce(e),n=Tt(e);return r>=n.height-o.height-t}),K())}var lr={drawer:P("[data-md-toggle=drawer]"),search:P("[data-md-toggle=search]")};function rn(e){return lr[e].checked}function Je(e,t){lr[e].checked!==t&&lr[e].click()}function Ve(e){let t=lr[e];return d(t,"change").pipe(m(()=>t.checked),Q(t.checked))}function wa(e,t){switch(e.constructor){case HTMLInputElement:return e.type==="radio"?/^Arrow/.test(t):!0;case HTMLSelectElement:case HTMLTextAreaElement:return!0;default:return e.isContentEditable}}function Ta(){return S(d(window,"compositionstart").pipe(m(()=>!0)),d(window,"compositionend").pipe(m(()=>!1))).pipe(Q(!1))}function on(){let e=d(window,"keydown").pipe(b(t=>!(t.metaKey||t.ctrlKey)),m(t=>({mode:rn("search")?"search":"global",type:t.key,claim(){t.preventDefault(),t.stopPropagation()}})),b(({mode:t,type:r})=>{if(t==="global"){let o=Re();if(typeof o!="undefined")return!wa(o,r)}return!0}),pe());return Ta().pipe(v(t=>t?O:e))}function xe(){return new URL(location.href)}function pt(e,t=!1){if(B("navigation.instant")&&!t){let r=x("a",{href:e.href});document.body.appendChild(r),r.click(),r.remove()}else location.href=e.href}function nn(){return new g}function an(){return location.hash.slice(1)}function sn(e){let t=x("a",{href:e});t.addEventListener("click",r=>r.stopPropagation()),t.click()}function Sa(e){return S(d(window,"hashchange"),e).pipe(m(an),Q(an()),b(t=>t.length>0),G(1))}function cn(e){return Sa(e).pipe(m(t=>fe(`[id="${t}"]`)),b(t=>typeof t!="undefined"))}function $t(e){let t=matchMedia(e);return ar(r=>t.addListener(()=>r(t.matches))).pipe(Q(t.matches))}function pn(){let e=matchMedia("print");return S(d(window,"beforeprint").pipe(m(()=>!0)),d(window,"afterprint").pipe(m(()=>!1))).pipe(Q(e.matches))}function Nr(e,t){return e.pipe(v(r=>r?t():O))}function zr(e,t){return new F(r=>{let o=new XMLHttpRequest;return o.open("GET",`${e}`),o.responseType="blob",o.addEventListener("load",()=>{o.status>=200&&o.status<300?(r.next(o.response),r.complete()):r.error(new Error(o.statusText))}),o.addEventListener("error",()=>{r.error(new Error("Network error"))}),o.addEventListener("abort",()=>{r.complete()}),typeof(t==null?void 0:t.progress$)!="undefined"&&(o.addEventListener("progress",n=>{var i;if(n.lengthComputable)t.progress$.next(n.loaded/n.total*100);else{let a=(i=o.getResponseHeader("Content-Length"))!=null?i:0;t.progress$.next(n.loaded/+a*100)}}),t.progress$.next(5)),o.send(),()=>o.abort()})}function Ne(e,t){return zr(e,t).pipe(v(r=>r.text()),m(r=>JSON.parse(r)),G(1))}function ln(e,t){let r=new DOMParser;return zr(e,t).pipe(v(o=>o.text()),m(o=>r.parseFromString(o,"text/html")),G(1))}function mn(e,t){let r=new DOMParser;return zr(e,t).pipe(v(o=>o.text()),m(o=>r.parseFromString(o,"text/xml")),G(1))}function fn(){return{x:Math.max(0,scrollX),y:Math.max(0,scrollY)}}function un(){return S(d(window,"scroll",{passive:!0}),d(window,"resize",{passive:!0})).pipe(m(fn),Q(fn()))}function dn(){return{width:innerWidth,height:innerHeight}}function hn(){return d(window,"resize",{passive:!0}).pipe(m(dn),Q(dn()))}function bn(){return z([un(),hn()]).pipe(m(([e,t])=>({offset:e,size:t})),G(1))}function mr(e,{viewport$:t,header$:r}){let o=t.pipe(Z("size")),n=z([o,r]).pipe(m(()=>Ue(e)));return z([r,t,n]).pipe(m(([{height:i},{offset:a,size:s},{x:p,y:c}])=>({offset:{x:a.x-p,y:a.y-c+i},size:s})))}function Oa(e){return d(e,"message",t=>t.data)}function Ma(e){let t=new g;return t.subscribe(r=>e.postMessage(r)),t}function vn(e,t=new Worker(e)){let r=Oa(t),o=Ma(t),n=new g;n.subscribe(o);let i=o.pipe(X(),ne(!0));return n.pipe(X(),Pe(r.pipe(U(i))),pe())}var La=P("#__config"),St=JSON.parse(La.textContent);St.base=`${new URL(St.base,xe())}`;function ye(){return St}function B(e){return St.features.includes(e)}function Ee(e,t){return typeof t!="undefined"?St.translations[e].replace("#",t.toString()):St.translations[e]}function Se(e,t=document){return P(`[data-md-component=${e}]`,t)}function ae(e,t=document){return $(`[data-md-component=${e}]`,t)}function _a(e){let t=P(".md-typeset > :first-child",e);return d(t,"click",{once:!0}).pipe(m(()=>P(".md-typeset",e)),m(r=>({hash:__md_hash(r.innerHTML)})))}function gn(e){if(!B("announce.dismiss")||!e.childElementCount)return O;if(!e.hidden){let t=P(".md-typeset",e);__md_hash(t.innerHTML)===__md_get("__announce")&&(e.hidden=!0)}return C(()=>{let t=new g;return t.subscribe(({hash:r})=>{e.hidden=!0,__md_set("__announce",r)}),_a(e).pipe(E(r=>t.next(r)),L(()=>t.complete()),m(r=>R({ref:e},r)))})}function Aa(e,{target$:t}){return t.pipe(m(r=>({hidden:r!==e})))}function xn(e,t){let r=new g;return r.subscribe(({hidden:o})=>{e.hidden=o}),Aa(e,t).pipe(E(o=>r.next(o)),L(()=>r.complete()),m(o=>R({ref:e},o)))}function Pt(e,t){return t==="inline"?x("div",{class:"md-tooltip md-tooltip--inline",id:e,role:"tooltip"},x("div",{class:"md-tooltip__inner md-typeset"})):x("div",{class:"md-tooltip",id:e,role:"tooltip"},x("div",{class:"md-tooltip__inner md-typeset"}))}function yn(...e){return x("div",{class:"md-tooltip2",role:"tooltip"},x("div",{class:"md-tooltip2__inner md-typeset"},e))}function En(e,t){if(t=t?`${t}_annotation_${e}`:void 0,t){let r=t?`#${t}`:void 0;return x("aside",{class:"md-annotation",tabIndex:0},Pt(t),x("a",{href:r,class:"md-annotation__index",tabIndex:-1},x("span",{"data-md-annotation-id":e})))}else return x("aside",{class:"md-annotation",tabIndex:0},Pt(t),x("span",{class:"md-annotation__index",tabIndex:-1},x("span",{"data-md-annotation-id":e})))}function wn(e){return x("button",{class:"md-clipboard md-icon",title:Ee("clipboard.copy"),"data-clipboard-target":`#${e} > code`})}function qr(e,t){let r=t&2,o=t&1,n=Object.keys(e.terms).filter(p=>!e.terms[p]).reduce((p,c)=>[...p,x("del",null,c)," "],[]).slice(0,-1),i=ye(),a=new URL(e.location,i.base);B("search.highlight")&&a.searchParams.set("h",Object.entries(e.terms).filter(([,p])=>p).reduce((p,[c])=>`${p} ${c}`.trim(),""));let{tags:s}=ye();return x("a",{href:`${a}`,class:"md-search-result__link",tabIndex:-1},x("article",{class:"md-search-result__article md-typeset","data-md-score":e.score.toFixed(2)},r>0&&x("div",{class:"md-search-result__icon md-icon"}),r>0&&x("h1",null,e.title),r<=0&&x("h2",null,e.title),o>0&&e.text.length>0&&e.text,e.tags&&e.tags.map(p=>{let c=s?p in s?`md-tag-icon md-tag--${s[p]}`:"md-tag-icon":"";return x("span",{class:`md-tag ${c}`},p)}),o>0&&n.length>0&&x("p",{class:"md-search-result__terms"},Ee("search.result.term.missing"),": ",...n)))}function Tn(e){let t=e[0].score,r=[...e],o=ye(),n=r.findIndex(l=>!`${new URL(l.location,o.base)}`.includes("#")),[i]=r.splice(n,1),a=r.findIndex(l=>l.scoreqr(l,1)),...p.length?[x("details",{class:"md-search-result__more"},x("summary",{tabIndex:-1},x("div",null,p.length>0&&p.length===1?Ee("search.result.more.one"):Ee("search.result.more.other",p.length))),...p.map(l=>qr(l,1)))]:[]];return x("li",{class:"md-search-result__item"},c)}function Sn(e){return x("ul",{class:"md-source__facts"},Object.entries(e).map(([t,r])=>x("li",{class:`md-source__fact md-source__fact--${t}`},typeof r=="number"?sr(r):r)))}function Qr(e){let t=`tabbed-control tabbed-control--${e}`;return x("div",{class:t,hidden:!0},x("button",{class:"tabbed-button",tabIndex:-1,"aria-hidden":"true"}))}function On(e){return x("div",{class:"md-typeset__scrollwrap"},x("div",{class:"md-typeset__table"},e))}function Ca(e){var o;let t=ye(),r=new URL(`../${e.version}/`,t.base);return x("li",{class:"md-version__item"},x("a",{href:`${r}`,class:"md-version__link"},e.title,((o=t.version)==null?void 0:o.alias)&&e.aliases.length>0&&x("span",{class:"md-version__alias"},e.aliases[0])))}function Mn(e,t){var o;let r=ye();return e=e.filter(n=>{var i;return!((i=n.properties)!=null&&i.hidden)}),x("div",{class:"md-version"},x("button",{class:"md-version__current","aria-label":Ee("select.version")},t.title,((o=r.version)==null?void 0:o.alias)&&t.aliases.length>0&&x("span",{class:"md-version__alias"},t.aliases[0])),x("ul",{class:"md-version__list"},e.map(Ca)))}var Ha=0;function ka(e){let t=z([et(e),kt(e)]).pipe(m(([o,n])=>o||n),K()),r=C(()=>Jo(e)).pipe(oe(De),ct(1),m(()=>Xo(e)));return t.pipe(Ae(o=>o),v(()=>z([t,r])),m(([o,n])=>({active:o,offset:n})),pe())}function $a(e,t){let{content$:r,viewport$:o}=t,n=`__tooltip2_${Ha++}`;return C(()=>{let i=new g,a=new _r(!1);i.pipe(X(),ne(!1)).subscribe(a);let s=a.pipe(Ht(c=>Me(+!c*250,Hr)),K(),v(c=>c?r:O),E(c=>c.id=n),pe());z([i.pipe(m(({active:c})=>c)),s.pipe(v(c=>kt(c,250)),Q(!1))]).pipe(m(c=>c.some(l=>l))).subscribe(a);let p=a.pipe(b(c=>c),ee(s,o),m(([c,l,{size:f}])=>{let u=e.getBoundingClientRect(),h=u.width/2;if(l.role==="tooltip")return{x:h,y:8+u.height};if(u.y>=f.height/2){let{height:w}=ce(l);return{x:h,y:-16-w}}else return{x:h,y:16+u.height}}));return z([s,i,p]).subscribe(([c,{offset:l},f])=>{c.style.setProperty("--md-tooltip-host-x",`${l.x}px`),c.style.setProperty("--md-tooltip-host-y",`${l.y}px`),c.style.setProperty("--md-tooltip-x",`${f.x}px`),c.style.setProperty("--md-tooltip-y",`${f.y}px`),c.classList.toggle("md-tooltip2--top",f.y<0),c.classList.toggle("md-tooltip2--bottom",f.y>=0)}),a.pipe(b(c=>c),ee(s,(c,l)=>l),b(c=>c.role==="tooltip")).subscribe(c=>{let l=ce(P(":scope > *",c));c.style.setProperty("--md-tooltip-width",`${l.width}px`),c.style.setProperty("--md-tooltip-tail","0px")}),a.pipe(K(),be(me),ee(s)).subscribe(([c,l])=>{l.classList.toggle("md-tooltip2--active",c)}),z([a.pipe(b(c=>c)),s]).subscribe(([c,l])=>{l.role==="dialog"?(e.setAttribute("aria-controls",n),e.setAttribute("aria-haspopup","dialog")):e.setAttribute("aria-describedby",n)}),a.pipe(b(c=>!c)).subscribe(()=>{e.removeAttribute("aria-controls"),e.removeAttribute("aria-describedby"),e.removeAttribute("aria-haspopup")}),ka(e).pipe(E(c=>i.next(c)),L(()=>i.complete()),m(c=>R({ref:e},c)))})}function lt(e,{viewport$:t},r=document.body){return $a(e,{content$:new F(o=>{let n=e.title,i=yn(n);return o.next(i),e.removeAttribute("title"),r.append(i),()=>{i.remove(),e.setAttribute("title",n)}}),viewport$:t})}function Pa(e,t){let r=C(()=>z([Zo(e),De(t)])).pipe(m(([{x:o,y:n},i])=>{let{width:a,height:s}=ce(e);return{x:o-i.x+a/2,y:n-i.y+s/2}}));return et(e).pipe(v(o=>r.pipe(m(n=>({active:o,offset:n})),Te(+!o||1/0))))}function Ln(e,t,{target$:r}){let[o,n]=Array.from(e.children);return C(()=>{let i=new g,a=i.pipe(X(),ne(!0));return i.subscribe({next({offset:s}){e.style.setProperty("--md-tooltip-x",`${s.x}px`),e.style.setProperty("--md-tooltip-y",`${s.y}px`)},complete(){e.style.removeProperty("--md-tooltip-x"),e.style.removeProperty("--md-tooltip-y")}}),tt(e).pipe(U(a)).subscribe(s=>{e.toggleAttribute("data-md-visible",s)}),S(i.pipe(b(({active:s})=>s)),i.pipe(_e(250),b(({active:s})=>!s))).subscribe({next({active:s}){s?e.prepend(o):o.remove()},complete(){e.prepend(o)}}),i.pipe(Le(16,me)).subscribe(({active:s})=>{o.classList.toggle("md-tooltip--active",s)}),i.pipe(ct(125,me),b(()=>!!e.offsetParent),m(()=>e.offsetParent.getBoundingClientRect()),m(({x:s})=>s)).subscribe({next(s){s?e.style.setProperty("--md-tooltip-0",`${-s}px`):e.style.removeProperty("--md-tooltip-0")},complete(){e.style.removeProperty("--md-tooltip-0")}}),d(n,"click").pipe(U(a),b(s=>!(s.metaKey||s.ctrlKey))).subscribe(s=>{s.stopPropagation(),s.preventDefault()}),d(n,"mousedown").pipe(U(a),ee(i)).subscribe(([s,{active:p}])=>{var c;if(s.button!==0||s.metaKey||s.ctrlKey)s.preventDefault();else if(p){s.preventDefault();let l=e.parentElement.closest(".md-annotation");l instanceof HTMLElement?l.focus():(c=Re())==null||c.blur()}}),r.pipe(U(a),b(s=>s===o),Ge(125)).subscribe(()=>e.focus()),Pa(e,t).pipe(E(s=>i.next(s)),L(()=>i.complete()),m(s=>R({ref:e},s)))})}function Ra(e){return e.tagName==="CODE"?$(".c, .c1, .cm",e):[e]}function Ia(e){let t=[];for(let r of Ra(e)){let o=[],n=document.createNodeIterator(r,NodeFilter.SHOW_TEXT);for(let i=n.nextNode();i;i=n.nextNode())o.push(i);for(let i of o){let a;for(;a=/(\(\d+\))(!)?/.exec(i.textContent);){let[,s,p]=a;if(typeof p=="undefined"){let c=i.splitText(a.index);i=c.splitText(s.length),t.push(c)}else{i.textContent=s,t.push(i);break}}}}return t}function _n(e,t){t.append(...Array.from(e.childNodes))}function fr(e,t,{target$:r,print$:o}){let n=t.closest("[id]"),i=n==null?void 0:n.id,a=new Map;for(let s of Ia(t)){let[,p]=s.textContent.match(/\((\d+)\)/);fe(`:scope > li:nth-child(${p})`,e)&&(a.set(p,En(p,i)),s.replaceWith(a.get(p)))}return a.size===0?O:C(()=>{let s=new g,p=s.pipe(X(),ne(!0)),c=[];for(let[l,f]of a)c.push([P(".md-typeset",f),P(`:scope > li:nth-child(${l})`,e)]);return o.pipe(U(p)).subscribe(l=>{e.hidden=!l,e.classList.toggle("md-annotation-list",l);for(let[f,u]of c)l?_n(f,u):_n(u,f)}),S(...[...a].map(([,l])=>Ln(l,t,{target$:r}))).pipe(L(()=>s.complete()),pe())})}function An(e){if(e.nextElementSibling){let t=e.nextElementSibling;if(t.tagName==="OL")return t;if(t.tagName==="P"&&!t.children.length)return An(t)}}function Cn(e,t){return C(()=>{let r=An(e);return typeof r!="undefined"?fr(r,e,t):O})}var Hn=Vt(Yr());var Fa=0;function kn(e){if(e.nextElementSibling){let t=e.nextElementSibling;if(t.tagName==="OL")return t;if(t.tagName==="P"&&!t.children.length)return kn(t)}}function ja(e){return ge(e).pipe(m(({width:t})=>({scrollable:Tt(e).width>t})),Z("scrollable"))}function $n(e,t){let{matches:r}=matchMedia("(hover)"),o=C(()=>{let n=new g,i=n.pipe(Fr(1));n.subscribe(({scrollable:c})=>{c&&r?e.setAttribute("tabindex","0"):e.removeAttribute("tabindex")});let a=[];if(Hn.default.isSupported()&&(e.closest(".copy")||B("content.code.copy")&&!e.closest(".no-copy"))){let c=e.closest("pre");c.id=`__code_${Fa++}`;let l=wn(c.id);c.insertBefore(l,e),B("content.tooltips")&&a.push(lt(l,{viewport$}))}let s=e.closest(".highlight");if(s instanceof HTMLElement){let c=kn(s);if(typeof c!="undefined"&&(s.classList.contains("annotate")||B("content.code.annotate"))){let l=fr(c,e,t);a.push(ge(s).pipe(U(i),m(({width:f,height:u})=>f&&u),K(),v(f=>f?l:O)))}}return $(":scope > span[id]",e).length&&e.classList.add("md-code__content"),ja(e).pipe(E(c=>n.next(c)),L(()=>n.complete()),m(c=>R({ref:e},c)),Pe(...a))});return B("content.lazy")?tt(e).pipe(b(n=>n),Te(1),v(()=>o)):o}function Wa(e,{target$:t,print$:r}){let o=!0;return S(t.pipe(m(n=>n.closest("details:not([open])")),b(n=>e===n),m(()=>({action:"open",reveal:!0}))),r.pipe(b(n=>n||!o),E(()=>o=e.open),m(n=>({action:n?"open":"close"}))))}function Pn(e,t){return C(()=>{let r=new g;return r.subscribe(({action:o,reveal:n})=>{e.toggleAttribute("open",o==="open"),n&&e.scrollIntoView()}),Wa(e,t).pipe(E(o=>r.next(o)),L(()=>r.complete()),m(o=>R({ref:e},o)))})}var Rn=".node circle,.node ellipse,.node path,.node polygon,.node rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}marker{fill:var(--md-mermaid-edge-color)!important}.edgeLabel .label rect{fill:#0000}.label{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.label foreignObject{line-height:normal;overflow:visible}.label div .edgeLabel{color:var(--md-mermaid-label-fg-color)}.edgeLabel,.edgeLabel rect,.label div .edgeLabel{background-color:var(--md-mermaid-label-bg-color)}.edgeLabel,.edgeLabel rect{fill:var(--md-mermaid-label-bg-color);color:var(--md-mermaid-edge-color)}.edgePath .path,.flowchart-link{stroke:var(--md-mermaid-edge-color);stroke-width:.05rem}.edgePath .arrowheadPath{fill:var(--md-mermaid-edge-color);stroke:none}.cluster rect{fill:var(--md-default-fg-color--lightest);stroke:var(--md-default-fg-color--lighter)}.cluster span{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}g #flowchart-circleEnd,g #flowchart-circleStart,g #flowchart-crossEnd,g #flowchart-crossStart,g #flowchart-pointEnd,g #flowchart-pointStart{stroke:none}g.classGroup line,g.classGroup rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}g.classGroup text{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.classLabel .box{fill:var(--md-mermaid-label-bg-color);background-color:var(--md-mermaid-label-bg-color);opacity:1}.classLabel .label{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.node .divider{stroke:var(--md-mermaid-node-fg-color)}.relation{stroke:var(--md-mermaid-edge-color)}.cardinality{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.cardinality text{fill:inherit!important}defs #classDiagram-compositionEnd,defs #classDiagram-compositionStart,defs #classDiagram-dependencyEnd,defs #classDiagram-dependencyStart,defs #classDiagram-extensionEnd,defs #classDiagram-extensionStart{fill:var(--md-mermaid-edge-color)!important;stroke:var(--md-mermaid-edge-color)!important}defs #classDiagram-aggregationEnd,defs #classDiagram-aggregationStart{fill:var(--md-mermaid-label-bg-color)!important;stroke:var(--md-mermaid-edge-color)!important}g.stateGroup rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}g.stateGroup .state-title{fill:var(--md-mermaid-label-fg-color)!important;font-family:var(--md-mermaid-font-family)}g.stateGroup .composit{fill:var(--md-mermaid-label-bg-color)}.nodeLabel,.nodeLabel p{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}a .nodeLabel{text-decoration:underline}.node circle.state-end,.node circle.state-start,.start-state{fill:var(--md-mermaid-edge-color);stroke:none}.end-state-inner,.end-state-outer{fill:var(--md-mermaid-edge-color)}.end-state-inner,.node circle.state-end{stroke:var(--md-mermaid-label-bg-color)}.transition{stroke:var(--md-mermaid-edge-color)}[id^=state-fork] rect,[id^=state-join] rect{fill:var(--md-mermaid-edge-color)!important;stroke:none!important}.statediagram-cluster.statediagram-cluster .inner{fill:var(--md-default-bg-color)}.statediagram-cluster rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}.statediagram-state rect.divider{fill:var(--md-default-fg-color--lightest);stroke:var(--md-default-fg-color--lighter)}defs #statediagram-barbEnd{stroke:var(--md-mermaid-edge-color)}.attributeBoxEven,.attributeBoxOdd{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}.entityBox{fill:var(--md-mermaid-label-bg-color);stroke:var(--md-mermaid-node-fg-color)}.entityLabel{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.relationshipLabelBox{fill:var(--md-mermaid-label-bg-color);fill-opacity:1;background-color:var(--md-mermaid-label-bg-color);opacity:1}.relationshipLabel{fill:var(--md-mermaid-label-fg-color)}.relationshipLine{stroke:var(--md-mermaid-edge-color)}defs #ONE_OR_MORE_END *,defs #ONE_OR_MORE_START *,defs #ONLY_ONE_END *,defs #ONLY_ONE_START *,defs #ZERO_OR_MORE_END *,defs #ZERO_OR_MORE_START *,defs #ZERO_OR_ONE_END *,defs #ZERO_OR_ONE_START *{stroke:var(--md-mermaid-edge-color)!important}defs #ZERO_OR_MORE_END circle,defs #ZERO_OR_MORE_START circle{fill:var(--md-mermaid-label-bg-color)}.actor{fill:var(--md-mermaid-sequence-actor-bg-color);stroke:var(--md-mermaid-sequence-actor-border-color)}text.actor>tspan{fill:var(--md-mermaid-sequence-actor-fg-color);font-family:var(--md-mermaid-font-family)}line{stroke:var(--md-mermaid-sequence-actor-line-color)}.actor-man circle,.actor-man line{fill:var(--md-mermaid-sequence-actorman-bg-color);stroke:var(--md-mermaid-sequence-actorman-line-color)}.messageLine0,.messageLine1{stroke:var(--md-mermaid-sequence-message-line-color)}.note{fill:var(--md-mermaid-sequence-note-bg-color);stroke:var(--md-mermaid-sequence-note-border-color)}.loopText,.loopText>tspan,.messageText,.noteText>tspan{stroke:none;font-family:var(--md-mermaid-font-family)!important}.messageText{fill:var(--md-mermaid-sequence-message-fg-color)}.loopText,.loopText>tspan{fill:var(--md-mermaid-sequence-loop-fg-color)}.noteText>tspan{fill:var(--md-mermaid-sequence-note-fg-color)}#arrowhead path{fill:var(--md-mermaid-sequence-message-line-color);stroke:none}.loopLine{fill:var(--md-mermaid-sequence-loop-bg-color);stroke:var(--md-mermaid-sequence-loop-border-color)}.labelBox{fill:var(--md-mermaid-sequence-label-bg-color);stroke:none}.labelText,.labelText>span{fill:var(--md-mermaid-sequence-label-fg-color);font-family:var(--md-mermaid-font-family)}.sequenceNumber{fill:var(--md-mermaid-sequence-number-fg-color)}rect.rect{fill:var(--md-mermaid-sequence-box-bg-color);stroke:none}rect.rect+text.text{fill:var(--md-mermaid-sequence-box-fg-color)}defs #sequencenumber{fill:var(--md-mermaid-sequence-number-bg-color)!important}";var Br,Da=0;function Va(){return typeof mermaid=="undefined"||mermaid instanceof Element?wt("https://unpkg.com/mermaid@10/dist/mermaid.min.js"):I(void 0)}function In(e){return e.classList.remove("mermaid"),Br||(Br=Va().pipe(E(()=>mermaid.initialize({startOnLoad:!1,themeCSS:Rn,sequence:{actorFontSize:"16px",messageFontSize:"16px",noteFontSize:"16px"}})),m(()=>{}),G(1))),Br.subscribe(()=>ao(this,null,function*(){e.classList.add("mermaid");let t=`__mermaid_${Da++}`,r=x("div",{class:"mermaid"}),o=e.textContent,{svg:n,fn:i}=yield mermaid.render(t,o),a=r.attachShadow({mode:"closed"});a.innerHTML=n,e.replaceWith(r),i==null||i(a)})),Br.pipe(m(()=>({ref:e})))}var Fn=x("table");function jn(e){return e.replaceWith(Fn),Fn.replaceWith(On(e)),I({ref:e})}function Na(e){let t=e.find(r=>r.checked)||e[0];return S(...e.map(r=>d(r,"change").pipe(m(()=>P(`label[for="${r.id}"]`))))).pipe(Q(P(`label[for="${t.id}"]`)),m(r=>({active:r})))}function Wn(e,{viewport$:t,target$:r}){let o=P(".tabbed-labels",e),n=$(":scope > input",e),i=Qr("prev");e.append(i);let a=Qr("next");return e.append(a),C(()=>{let s=new g,p=s.pipe(X(),ne(!0));z([s,ge(e),tt(e)]).pipe(U(p),Le(1,me)).subscribe({next([{active:c},l]){let f=Ue(c),{width:u}=ce(c);e.style.setProperty("--md-indicator-x",`${f.x}px`),e.style.setProperty("--md-indicator-width",`${u}px`);let h=pr(o);(f.xh.x+l.width)&&o.scrollTo({left:Math.max(0,f.x-16),behavior:"smooth"})},complete(){e.style.removeProperty("--md-indicator-x"),e.style.removeProperty("--md-indicator-width")}}),z([De(o),ge(o)]).pipe(U(p)).subscribe(([c,l])=>{let f=Tt(o);i.hidden=c.x<16,a.hidden=c.x>f.width-l.width-16}),S(d(i,"click").pipe(m(()=>-1)),d(a,"click").pipe(m(()=>1))).pipe(U(p)).subscribe(c=>{let{width:l}=ce(o);o.scrollBy({left:l*c,behavior:"smooth"})}),r.pipe(U(p),b(c=>n.includes(c))).subscribe(c=>c.click()),o.classList.add("tabbed-labels--linked");for(let c of n){let l=P(`label[for="${c.id}"]`);l.replaceChildren(x("a",{href:`#${l.htmlFor}`,tabIndex:-1},...Array.from(l.childNodes))),d(l.firstElementChild,"click").pipe(U(p),b(f=>!(f.metaKey||f.ctrlKey)),E(f=>{f.preventDefault(),f.stopPropagation()})).subscribe(()=>{history.replaceState({},"",`#${l.htmlFor}`),l.click()})}return B("content.tabs.link")&&s.pipe(Ce(1),ee(t)).subscribe(([{active:c},{offset:l}])=>{let f=c.innerText.trim();if(c.hasAttribute("data-md-switching"))c.removeAttribute("data-md-switching");else{let u=e.offsetTop-l.y;for(let w of $("[data-tabs]"))for(let A of $(":scope > input",w)){let te=P(`label[for="${A.id}"]`);if(te!==c&&te.innerText.trim()===f){te.setAttribute("data-md-switching",""),A.click();break}}window.scrollTo({top:e.offsetTop-u});let h=__md_get("__tabs")||[];__md_set("__tabs",[...new Set([f,...h])])}}),s.pipe(U(p)).subscribe(()=>{for(let c of $("audio, video",e))c.pause()}),Na(n).pipe(E(c=>s.next(c)),L(()=>s.complete()),m(c=>R({ref:e},c)))}).pipe(Qe(se))}function Un(e,{viewport$:t,target$:r,print$:o}){return S(...$(".annotate:not(.highlight)",e).map(n=>Cn(n,{target$:r,print$:o})),...$("pre:not(.mermaid) > code",e).map(n=>$n(n,{target$:r,print$:o})),...$("pre.mermaid",e).map(n=>In(n)),...$("table:not([class])",e).map(n=>jn(n)),...$("details",e).map(n=>Pn(n,{target$:r,print$:o})),...$("[data-tabs]",e).map(n=>Wn(n,{viewport$:t,target$:r})),...$("[title]",e).filter(()=>B("content.tooltips")).map(n=>lt(n,{viewport$:t})))}function za(e,{alert$:t}){return t.pipe(v(r=>S(I(!0),I(!1).pipe(Ge(2e3))).pipe(m(o=>({message:r,active:o})))))}function Dn(e,t){let r=P(".md-typeset",e);return C(()=>{let o=new g;return o.subscribe(({message:n,active:i})=>{e.classList.toggle("md-dialog--active",i),r.textContent=n}),za(e,t).pipe(E(n=>o.next(n)),L(()=>o.complete()),m(n=>R({ref:e},n)))})}var qa=0;function Qa(e,t){document.body.append(e);let{width:r}=ce(e);e.style.setProperty("--md-tooltip-width",`${r}px`),e.remove();let o=cr(t),n=typeof o!="undefined"?De(o):I({x:0,y:0}),i=S(et(t),kt(t)).pipe(K());return z([i,n]).pipe(m(([a,s])=>{let{x:p,y:c}=Ue(t),l=ce(t),f=t.closest("table");return f&&t.parentElement&&(p+=f.offsetLeft+t.parentElement.offsetLeft,c+=f.offsetTop+t.parentElement.offsetTop),{active:a,offset:{x:p-s.x+l.width/2-r/2,y:c-s.y+l.height+8}}}))}function Vn(e){let t=e.title;if(!t.length)return O;let r=`__tooltip_${qa++}`,o=Pt(r,"inline"),n=P(".md-typeset",o);return n.innerHTML=t,C(()=>{let i=new g;return i.subscribe({next({offset:a}){o.style.setProperty("--md-tooltip-x",`${a.x}px`),o.style.setProperty("--md-tooltip-y",`${a.y}px`)},complete(){o.style.removeProperty("--md-tooltip-x"),o.style.removeProperty("--md-tooltip-y")}}),S(i.pipe(b(({active:a})=>a)),i.pipe(_e(250),b(({active:a})=>!a))).subscribe({next({active:a}){a?(e.insertAdjacentElement("afterend",o),e.setAttribute("aria-describedby",r),e.removeAttribute("title")):(o.remove(),e.removeAttribute("aria-describedby"),e.setAttribute("title",t))},complete(){o.remove(),e.removeAttribute("aria-describedby"),e.setAttribute("title",t)}}),i.pipe(Le(16,me)).subscribe(({active:a})=>{o.classList.toggle("md-tooltip--active",a)}),i.pipe(ct(125,me),b(()=>!!e.offsetParent),m(()=>e.offsetParent.getBoundingClientRect()),m(({x:a})=>a)).subscribe({next(a){a?o.style.setProperty("--md-tooltip-0",`${-a}px`):o.style.removeProperty("--md-tooltip-0")},complete(){o.style.removeProperty("--md-tooltip-0")}}),Qa(o,e).pipe(E(a=>i.next(a)),L(()=>i.complete()),m(a=>R({ref:e},a)))}).pipe(Qe(se))}function Ka({viewport$:e}){if(!B("header.autohide"))return I(!1);let t=e.pipe(m(({offset:{y:n}})=>n),Ye(2,1),m(([n,i])=>[nMath.abs(i-n.y)>100),m(([,[n]])=>n),K()),o=Ve("search");return z([e,o]).pipe(m(([{offset:n},i])=>n.y>400&&!i),K(),v(n=>n?r:I(!1)),Q(!1))}function Nn(e,t){return C(()=>z([ge(e),Ka(t)])).pipe(m(([{height:r},o])=>({height:r,hidden:o})),K((r,o)=>r.height===o.height&&r.hidden===o.hidden),G(1))}function zn(e,{header$:t,main$:r}){return C(()=>{let o=new g,n=o.pipe(X(),ne(!0));o.pipe(Z("active"),We(t)).subscribe(([{active:a},{hidden:s}])=>{e.classList.toggle("md-header--shadow",a&&!s),e.hidden=s});let i=ue($("[title]",e)).pipe(b(()=>B("content.tooltips")),oe(a=>Vn(a)));return r.subscribe(o),t.pipe(U(n),m(a=>R({ref:e},a)),Pe(i.pipe(U(n))))})}function Ya(e,{viewport$:t,header$:r}){return mr(e,{viewport$:t,header$:r}).pipe(m(({offset:{y:o}})=>{let{height:n}=ce(e);return{active:o>=n}}),Z("active"))}function qn(e,t){return C(()=>{let r=new g;r.subscribe({next({active:n}){e.classList.toggle("md-header__title--active",n)},complete(){e.classList.remove("md-header__title--active")}});let o=fe(".md-content h1");return typeof o=="undefined"?O:Ya(o,t).pipe(E(n=>r.next(n)),L(()=>r.complete()),m(n=>R({ref:e},n)))})}function Qn(e,{viewport$:t,header$:r}){let o=r.pipe(m(({height:i})=>i),K()),n=o.pipe(v(()=>ge(e).pipe(m(({height:i})=>({top:e.offsetTop,bottom:e.offsetTop+i})),Z("bottom"))));return z([o,n,t]).pipe(m(([i,{top:a,bottom:s},{offset:{y:p},size:{height:c}}])=>(c=Math.max(0,c-Math.max(0,a-p,i)-Math.max(0,c+p-s)),{offset:a-i,height:c,active:a-i<=p})),K((i,a)=>i.offset===a.offset&&i.height===a.height&&i.active===a.active))}function Ba(e){let t=__md_get("__palette")||{index:e.findIndex(o=>matchMedia(o.getAttribute("data-md-color-media")).matches)},r=Math.max(0,Math.min(t.index,e.length-1));return I(...e).pipe(oe(o=>d(o,"change").pipe(m(()=>o))),Q(e[r]),m(o=>({index:e.indexOf(o),color:{media:o.getAttribute("data-md-color-media"),scheme:o.getAttribute("data-md-color-scheme"),primary:o.getAttribute("data-md-color-primary"),accent:o.getAttribute("data-md-color-accent")}})),G(1))}function Kn(e){let t=$("input",e),r=x("meta",{name:"theme-color"});document.head.appendChild(r);let o=x("meta",{name:"color-scheme"});document.head.appendChild(o);let n=$t("(prefers-color-scheme: light)");return C(()=>{let i=new g;return i.subscribe(a=>{if(document.body.setAttribute("data-md-color-switching",""),a.color.media==="(prefers-color-scheme)"){let s=matchMedia("(prefers-color-scheme: light)"),p=document.querySelector(s.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");a.color.scheme=p.getAttribute("data-md-color-scheme"),a.color.primary=p.getAttribute("data-md-color-primary"),a.color.accent=p.getAttribute("data-md-color-accent")}for(let[s,p]of Object.entries(a.color))document.body.setAttribute(`data-md-color-${s}`,p);for(let s=0;sa.key==="Enter"),ee(i,(a,s)=>s)).subscribe(({index:a})=>{a=(a+1)%t.length,t[a].click(),t[a].focus()}),i.pipe(m(()=>{let a=Se("header"),s=window.getComputedStyle(a);return o.content=s.colorScheme,s.backgroundColor.match(/\d+/g).map(p=>(+p).toString(16).padStart(2,"0")).join("")})).subscribe(a=>r.content=`#${a}`),i.pipe(be(se)).subscribe(()=>{document.body.removeAttribute("data-md-color-switching")}),Ba(t).pipe(U(n.pipe(Ce(1))),st(),E(a=>i.next(a)),L(()=>i.complete()),m(a=>R({ref:e},a)))})}function Yn(e,{progress$:t}){return C(()=>{let r=new g;return r.subscribe(({value:o})=>{e.style.setProperty("--md-progress-value",`${o}`)}),t.pipe(E(o=>r.next({value:o})),L(()=>r.complete()),m(o=>({ref:e,value:o})))})}var Gr=Vt(Yr());function Ga(e){e.setAttribute("data-md-copying","");let t=e.closest("[data-copy]"),r=t?t.getAttribute("data-copy"):e.innerText;return e.removeAttribute("data-md-copying"),r.trimEnd()}function Bn({alert$:e}){Gr.default.isSupported()&&new F(t=>{new Gr.default("[data-clipboard-target], [data-clipboard-text]",{text:r=>r.getAttribute("data-clipboard-text")||Ga(P(r.getAttribute("data-clipboard-target")))}).on("success",r=>t.next(r))}).pipe(E(t=>{t.trigger.focus()}),m(()=>Ee("clipboard.copied"))).subscribe(e)}function Gn(e,t){return e.protocol=t.protocol,e.hostname=t.hostname,e}function Ja(e,t){let r=new Map;for(let o of $("url",e)){let n=P("loc",o),i=[Gn(new URL(n.textContent),t)];r.set(`${i[0]}`,i);for(let a of $("[rel=alternate]",o)){let s=a.getAttribute("href");s!=null&&i.push(Gn(new URL(s),t))}}return r}function ur(e){return mn(new URL("sitemap.xml",e)).pipe(m(t=>Ja(t,new URL(e))),ve(()=>I(new Map)))}function Xa(e,t){if(!(e.target instanceof Element))return O;let r=e.target.closest("a");if(r===null)return O;if(r.target||e.metaKey||e.ctrlKey)return O;let o=new URL(r.href);return o.search=o.hash="",t.has(`${o}`)?(e.preventDefault(),I(new URL(r.href))):O}function Jn(e){let t=new Map;for(let r of $(":scope > *",e.head))t.set(r.outerHTML,r);return t}function Xn(e){for(let t of $("[href], [src]",e))for(let r of["href","src"]){let o=t.getAttribute(r);if(o&&!/^(?:[a-z]+:)?\/\//i.test(o)){t[r]=t[r];break}}return I(e)}function Za(e){for(let o of["[data-md-component=announce]","[data-md-component=container]","[data-md-component=header-topic]","[data-md-component=outdated]","[data-md-component=logo]","[data-md-component=skip]",...B("navigation.tabs.sticky")?["[data-md-component=tabs]"]:[]]){let n=fe(o),i=fe(o,e);typeof n!="undefined"&&typeof i!="undefined"&&n.replaceWith(i)}let t=Jn(document);for(let[o,n]of Jn(e))t.has(o)?t.delete(o):document.head.appendChild(n);for(let o of t.values()){let n=o.getAttribute("name");n!=="theme-color"&&n!=="color-scheme"&&o.remove()}let r=Se("container");return je($("script",r)).pipe(v(o=>{let n=e.createElement("script");if(o.src){for(let i of o.getAttributeNames())n.setAttribute(i,o.getAttribute(i));return o.replaceWith(n),new F(i=>{n.onload=()=>i.complete()})}else return n.textContent=o.textContent,o.replaceWith(n),O}),X(),ne(document))}function Zn({location$:e,viewport$:t,progress$:r}){let o=ye();if(location.protocol==="file:")return O;let n=ur(o.base);I(document).subscribe(Xn);let i=d(document.body,"click").pipe(We(n),v(([p,c])=>Xa(p,c)),pe()),a=d(window,"popstate").pipe(m(xe),pe());i.pipe(ee(t)).subscribe(([p,{offset:c}])=>{history.replaceState(c,""),history.pushState(null,"",p)}),S(i,a).subscribe(e);let s=e.pipe(Z("pathname"),v(p=>ln(p,{progress$:r}).pipe(ve(()=>(pt(p,!0),O)))),v(Xn),v(Za),pe());return S(s.pipe(ee(e,(p,c)=>c)),s.pipe(v(()=>e),Z("pathname"),v(()=>e),Z("hash")),e.pipe(K((p,c)=>p.pathname===c.pathname&&p.hash===c.hash),v(()=>i),E(()=>history.back()))).subscribe(p=>{var c,l;history.state!==null||!p.hash?window.scrollTo(0,(l=(c=history.state)==null?void 0:c.y)!=null?l:0):(history.scrollRestoration="auto",sn(p.hash),history.scrollRestoration="manual")}),e.subscribe(()=>{history.scrollRestoration="manual"}),d(window,"beforeunload").subscribe(()=>{history.scrollRestoration="auto"}),t.pipe(Z("offset"),_e(100)).subscribe(({offset:p})=>{history.replaceState(p,"")}),s}var ri=Vt(ti());function oi(e){let t=e.separator.split("|").map(n=>n.replace(/(\(\?[!=<][^)]+\))/g,"").length===0?"\uFFFD":n).join("|"),r=new RegExp(t,"img"),o=(n,i,a)=>`${i}${a}`;return n=>{n=n.replace(/[\s*+\-:~^]+/g," ").trim();let i=new RegExp(`(^|${e.separator}|)(${n.replace(/[|\\{}()[\]^$+*?.-]/g,"\\$&").replace(r,"|")})`,"img");return a=>(0,ri.default)(a).replace(i,o).replace(/<\/mark>(\s+)]*>/img,"$1")}}function It(e){return e.type===1}function dr(e){return e.type===3}function ni(e,t){let r=vn(e);return S(I(location.protocol!=="file:"),Ve("search")).pipe(Ae(o=>o),v(()=>t)).subscribe(({config:o,docs:n})=>r.next({type:0,data:{config:o,docs:n,options:{suggest:B("search.suggest")}}})),r}function ii({document$:e}){let t=ye(),r=Ne(new URL("../versions.json",t.base)).pipe(ve(()=>O)),o=r.pipe(m(n=>{let[,i]=t.base.match(/([^/]+)\/?$/);return n.find(({version:a,aliases:s})=>a===i||s.includes(i))||n[0]}));r.pipe(m(n=>new Map(n.map(i=>[`${new URL(`../${i.version}/`,t.base)}`,i]))),v(n=>d(document.body,"click").pipe(b(i=>!i.metaKey&&!i.ctrlKey),ee(o),v(([i,a])=>{if(i.target instanceof Element){let s=i.target.closest("a");if(s&&!s.target&&n.has(s.href)){let p=s.href;return!i.target.closest(".md-version")&&n.get(p)===a?O:(i.preventDefault(),I(p))}}return O}),v(i=>ur(new URL(i)).pipe(m(a=>{let p=xe().href.replace(t.base,i);return a.has(p.split("#")[0])?new URL(p):new URL(i)})))))).subscribe(n=>pt(n,!0)),z([r,o]).subscribe(([n,i])=>{P(".md-header__topic").appendChild(Mn(n,i))}),e.pipe(v(()=>o)).subscribe(n=>{var a;let i=__md_get("__outdated",sessionStorage);if(i===null){i=!0;let s=((a=t.version)==null?void 0:a.default)||"latest";Array.isArray(s)||(s=[s]);e:for(let p of s)for(let c of n.aliases.concat(n.version))if(new RegExp(p,"i").test(c)){i=!1;break e}__md_set("__outdated",i,sessionStorage)}if(i)for(let s of ae("outdated"))s.hidden=!1})}function ns(e,{worker$:t}){let{searchParams:r}=xe();r.has("q")&&(Je("search",!0),e.value=r.get("q"),e.focus(),Ve("search").pipe(Ae(i=>!i)).subscribe(()=>{let i=xe();i.searchParams.delete("q"),history.replaceState({},"",`${i}`)}));let o=et(e),n=S(t.pipe(Ae(It)),d(e,"keyup"),o).pipe(m(()=>e.value),K());return z([n,o]).pipe(m(([i,a])=>({value:i,focus:a})),G(1))}function ai(e,{worker$:t}){let r=new g,o=r.pipe(X(),ne(!0));z([t.pipe(Ae(It)),r],(i,a)=>a).pipe(Z("value")).subscribe(({value:i})=>t.next({type:2,data:i})),r.pipe(Z("focus")).subscribe(({focus:i})=>{i&&Je("search",i)}),d(e.form,"reset").pipe(U(o)).subscribe(()=>e.focus());let n=P("header [for=__search]");return d(n,"click").subscribe(()=>e.focus()),ns(e,{worker$:t}).pipe(E(i=>r.next(i)),L(()=>r.complete()),m(i=>R({ref:e},i)),G(1))}function si(e,{worker$:t,query$:r}){let o=new g,n=tn(e.parentElement).pipe(b(Boolean)),i=e.parentElement,a=P(":scope > :first-child",e),s=P(":scope > :last-child",e);Ve("search").subscribe(l=>s.setAttribute("role",l?"list":"presentation")),o.pipe(ee(r),Ur(t.pipe(Ae(It)))).subscribe(([{items:l},{value:f}])=>{switch(l.length){case 0:a.textContent=f.length?Ee("search.result.none"):Ee("search.result.placeholder");break;case 1:a.textContent=Ee("search.result.one");break;default:let u=sr(l.length);a.textContent=Ee("search.result.other",u)}});let p=o.pipe(E(()=>s.innerHTML=""),v(({items:l})=>S(I(...l.slice(0,10)),I(...l.slice(10)).pipe(Ye(4),Vr(n),v(([f])=>f)))),m(Tn),pe());return p.subscribe(l=>s.appendChild(l)),p.pipe(oe(l=>{let f=fe("details",l);return typeof f=="undefined"?O:d(f,"toggle").pipe(U(o),m(()=>f))})).subscribe(l=>{l.open===!1&&l.offsetTop<=i.scrollTop&&i.scrollTo({top:l.offsetTop})}),t.pipe(b(dr),m(({data:l})=>l)).pipe(E(l=>o.next(l)),L(()=>o.complete()),m(l=>R({ref:e},l)))}function is(e,{query$:t}){return t.pipe(m(({value:r})=>{let o=xe();return o.hash="",r=r.replace(/\s+/g,"+").replace(/&/g,"%26").replace(/=/g,"%3D"),o.search=`q=${r}`,{url:o}}))}function ci(e,t){let r=new g,o=r.pipe(X(),ne(!0));return r.subscribe(({url:n})=>{e.setAttribute("data-clipboard-text",e.href),e.href=`${n}`}),d(e,"click").pipe(U(o)).subscribe(n=>n.preventDefault()),is(e,t).pipe(E(n=>r.next(n)),L(()=>r.complete()),m(n=>R({ref:e},n)))}function pi(e,{worker$:t,keyboard$:r}){let o=new g,n=Se("search-query"),i=S(d(n,"keydown"),d(n,"focus")).pipe(be(se),m(()=>n.value),K());return o.pipe(We(i),m(([{suggest:s},p])=>{let c=p.split(/([\s-]+)/);if(s!=null&&s.length&&c[c.length-1]){let l=s[s.length-1];l.startsWith(c[c.length-1])&&(c[c.length-1]=l)}else c.length=0;return c})).subscribe(s=>e.innerHTML=s.join("").replace(/\s/g," ")),r.pipe(b(({mode:s})=>s==="search")).subscribe(s=>{switch(s.type){case"ArrowRight":e.innerText.length&&n.selectionStart===n.value.length&&(n.value=e.innerText);break}}),t.pipe(b(dr),m(({data:s})=>s)).pipe(E(s=>o.next(s)),L(()=>o.complete()),m(()=>({ref:e})))}function li(e,{index$:t,keyboard$:r}){let o=ye();try{let n=ni(o.search,t),i=Se("search-query",e),a=Se("search-result",e);d(e,"click").pipe(b(({target:p})=>p instanceof Element&&!!p.closest("a"))).subscribe(()=>Je("search",!1)),r.pipe(b(({mode:p})=>p==="search")).subscribe(p=>{let c=Re();switch(p.type){case"Enter":if(c===i){let l=new Map;for(let f of $(":first-child [href]",a)){let u=f.firstElementChild;l.set(f,parseFloat(u.getAttribute("data-md-score")))}if(l.size){let[[f]]=[...l].sort(([,u],[,h])=>h-u);f.click()}p.claim()}break;case"Escape":case"Tab":Je("search",!1),i.blur();break;case"ArrowUp":case"ArrowDown":if(typeof c=="undefined")i.focus();else{let l=[i,...$(":not(details) > [href], summary, details[open] [href]",a)],f=Math.max(0,(Math.max(0,l.indexOf(c))+l.length+(p.type==="ArrowUp"?-1:1))%l.length);l[f].focus()}p.claim();break;default:i!==Re()&&i.focus()}}),r.pipe(b(({mode:p})=>p==="global")).subscribe(p=>{switch(p.type){case"f":case"s":case"/":i.focus(),i.select(),p.claim();break}});let s=ai(i,{worker$:n});return S(s,si(a,{worker$:n,query$:s})).pipe(Pe(...ae("search-share",e).map(p=>ci(p,{query$:s})),...ae("search-suggest",e).map(p=>pi(p,{worker$:n,keyboard$:r}))))}catch(n){return e.hidden=!0,Ke}}function mi(e,{index$:t,location$:r}){return z([t,r.pipe(Q(xe()),b(o=>!!o.searchParams.get("h")))]).pipe(m(([o,n])=>oi(o.config)(n.searchParams.get("h"))),m(o=>{var a;let n=new Map,i=document.createNodeIterator(e,NodeFilter.SHOW_TEXT);for(let s=i.nextNode();s;s=i.nextNode())if((a=s.parentElement)!=null&&a.offsetHeight){let p=s.textContent,c=o(p);c.length>p.length&&n.set(s,c)}for(let[s,p]of n){let{childNodes:c}=x("span",null,p);s.replaceWith(...Array.from(c))}return{ref:e,nodes:n}}))}function as(e,{viewport$:t,main$:r}){let o=e.closest(".md-grid"),n=o.offsetTop-o.parentElement.offsetTop;return z([r,t]).pipe(m(([{offset:i,height:a},{offset:{y:s}}])=>(a=a+Math.min(n,Math.max(0,s-i))-n,{height:a,locked:s>=i+n})),K((i,a)=>i.height===a.height&&i.locked===a.locked))}function Jr(e,o){var n=o,{header$:t}=n,r=io(n,["header$"]);let i=P(".md-sidebar__scrollwrap",e),{y:a}=Ue(i);return C(()=>{let s=new g,p=s.pipe(X(),ne(!0)),c=s.pipe(Le(0,me));return c.pipe(ee(t)).subscribe({next([{height:l},{height:f}]){i.style.height=`${l-2*a}px`,e.style.top=`${f}px`},complete(){i.style.height="",e.style.top=""}}),c.pipe(Ae()).subscribe(()=>{for(let l of $(".md-nav__link--active[href]",e)){if(!l.clientHeight)continue;let f=l.closest(".md-sidebar__scrollwrap");if(typeof f!="undefined"){let u=l.offsetTop-f.offsetTop,{height:h}=ce(f);f.scrollTo({top:u-h/2})}}}),ue($("label[tabindex]",e)).pipe(oe(l=>d(l,"click").pipe(be(se),m(()=>l),U(p)))).subscribe(l=>{let f=P(`[id="${l.htmlFor}"]`);P(`[aria-labelledby="${l.id}"]`).setAttribute("aria-expanded",`${f.checked}`)}),as(e,r).pipe(E(l=>s.next(l)),L(()=>s.complete()),m(l=>R({ref:e},l)))})}function fi(e,t){if(typeof t!="undefined"){let r=`https://api.github.com/repos/${e}/${t}`;return Ct(Ne(`${r}/releases/latest`).pipe(ve(()=>O),m(o=>({version:o.tag_name})),Be({})),Ne(r).pipe(ve(()=>O),m(o=>({stars:o.stargazers_count,forks:o.forks_count})),Be({}))).pipe(m(([o,n])=>R(R({},o),n)))}else{let r=`https://api.github.com/users/${e}`;return Ne(r).pipe(m(o=>({repositories:o.public_repos})),Be({}))}}function ui(e,t){let r=`https://${e}/api/v4/projects/${encodeURIComponent(t)}`;return Ne(r).pipe(ve(()=>O),m(({star_count:o,forks_count:n})=>({stars:o,forks:n})),Be({}))}function di(e){let t=e.match(/^.+github\.com\/([^/]+)\/?([^/]+)?/i);if(t){let[,r,o]=t;return fi(r,o)}if(t=e.match(/^.+?([^/]*gitlab[^/]+)\/(.+?)\/?$/i),t){let[,r,o]=t;return ui(r,o)}return O}var ss;function cs(e){return ss||(ss=C(()=>{let t=__md_get("__source",sessionStorage);if(t)return I(t);if(ae("consent").length){let o=__md_get("__consent");if(!(o&&o.github))return O}return di(e.href).pipe(E(o=>__md_set("__source",o,sessionStorage)))}).pipe(ve(()=>O),b(t=>Object.keys(t).length>0),m(t=>({facts:t})),G(1)))}function hi(e){let t=P(":scope > :last-child",e);return C(()=>{let r=new g;return r.subscribe(({facts:o})=>{t.appendChild(Sn(o)),t.classList.add("md-source__repository--active")}),cs(e).pipe(E(o=>r.next(o)),L(()=>r.complete()),m(o=>R({ref:e},o)))})}function ps(e,{viewport$:t,header$:r}){return ge(document.body).pipe(v(()=>mr(e,{header$:r,viewport$:t})),m(({offset:{y:o}})=>({hidden:o>=10})),Z("hidden"))}function bi(e,t){return C(()=>{let r=new g;return r.subscribe({next({hidden:o}){e.hidden=o},complete(){e.hidden=!1}}),(B("navigation.tabs.sticky")?I({hidden:!1}):ps(e,t)).pipe(E(o=>r.next(o)),L(()=>r.complete()),m(o=>R({ref:e},o)))})}function ls(e,{viewport$:t,header$:r}){let o=new Map,n=$(".md-nav__link",e);for(let s of n){let p=decodeURIComponent(s.hash.substring(1)),c=fe(`[id="${p}"]`);typeof c!="undefined"&&o.set(s,c)}let i=r.pipe(Z("height"),m(({height:s})=>{let p=Se("main"),c=P(":scope > :first-child",p);return s+.8*(c.offsetTop-p.offsetTop)}),pe());return ge(document.body).pipe(Z("height"),v(s=>C(()=>{let p=[];return I([...o].reduce((c,[l,f])=>{for(;p.length&&o.get(p[p.length-1]).tagName>=f.tagName;)p.pop();let u=f.offsetTop;for(;!u&&f.parentElement;)f=f.parentElement,u=f.offsetTop;let h=f.offsetParent;for(;h;h=h.offsetParent)u+=h.offsetTop;return c.set([...p=[...p,l]].reverse(),u)},new Map))}).pipe(m(p=>new Map([...p].sort(([,c],[,l])=>c-l))),We(i),v(([p,c])=>t.pipe(jr(([l,f],{offset:{y:u},size:h})=>{let w=u+h.height>=Math.floor(s.height);for(;f.length;){let[,A]=f[0];if(A-c=u&&!w)f=[l.pop(),...f];else break}return[l,f]},[[],[...p]]),K((l,f)=>l[0]===f[0]&&l[1]===f[1])))))).pipe(m(([s,p])=>({prev:s.map(([c])=>c),next:p.map(([c])=>c)})),Q({prev:[],next:[]}),Ye(2,1),m(([s,p])=>s.prev.length{let i=new g,a=i.pipe(X(),ne(!0));if(i.subscribe(({prev:s,next:p})=>{for(let[c]of p)c.classList.remove("md-nav__link--passed"),c.classList.remove("md-nav__link--active");for(let[c,[l]]of s.entries())l.classList.add("md-nav__link--passed"),l.classList.toggle("md-nav__link--active",c===s.length-1)}),B("toc.follow")){let s=S(t.pipe(_e(1),m(()=>{})),t.pipe(_e(250),m(()=>"smooth")));i.pipe(b(({prev:p})=>p.length>0),We(o.pipe(be(se))),ee(s)).subscribe(([[{prev:p}],c])=>{let[l]=p[p.length-1];if(l.offsetHeight){let f=cr(l);if(typeof f!="undefined"){let u=l.offsetTop-f.offsetTop,{height:h}=ce(f);f.scrollTo({top:u-h/2,behavior:c})}}})}return B("navigation.tracking")&&t.pipe(U(a),Z("offset"),_e(250),Ce(1),U(n.pipe(Ce(1))),st({delay:250}),ee(i)).subscribe(([,{prev:s}])=>{let p=xe(),c=s[s.length-1];if(c&&c.length){let[l]=c,{hash:f}=new URL(l.href);p.hash!==f&&(p.hash=f,history.replaceState({},"",`${p}`))}else p.hash="",history.replaceState({},"",`${p}`)}),ls(e,{viewport$:t,header$:r}).pipe(E(s=>i.next(s)),L(()=>i.complete()),m(s=>R({ref:e},s)))})}function ms(e,{viewport$:t,main$:r,target$:o}){let n=t.pipe(m(({offset:{y:a}})=>a),Ye(2,1),m(([a,s])=>a>s&&s>0),K()),i=r.pipe(m(({active:a})=>a));return z([i,n]).pipe(m(([a,s])=>!(a&&s)),K(),U(o.pipe(Ce(1))),ne(!0),st({delay:250}),m(a=>({hidden:a})))}function gi(e,{viewport$:t,header$:r,main$:o,target$:n}){let i=new g,a=i.pipe(X(),ne(!0));return i.subscribe({next({hidden:s}){e.hidden=s,s?(e.setAttribute("tabindex","-1"),e.blur()):e.removeAttribute("tabindex")},complete(){e.style.top="",e.hidden=!0,e.removeAttribute("tabindex")}}),r.pipe(U(a),Z("height")).subscribe(({height:s})=>{e.style.top=`${s+16}px`}),d(e,"click").subscribe(s=>{s.preventDefault(),window.scrollTo({top:0})}),ms(e,{viewport$:t,main$:o,target$:n}).pipe(E(s=>i.next(s)),L(()=>i.complete()),m(s=>R({ref:e},s)))}function xi({document$:e,viewport$:t}){e.pipe(v(()=>$(".md-ellipsis")),oe(r=>tt(r).pipe(U(e.pipe(Ce(1))),b(o=>o),m(()=>r),Te(1))),b(r=>r.offsetWidth{let o=r.innerText,n=r.closest("a")||r;return n.title=o,B("content.tooltips")?lt(n,{viewport$:t}).pipe(U(e.pipe(Ce(1))),L(()=>n.removeAttribute("title"))):O})).subscribe(),B("content.tooltips")&&e.pipe(v(()=>$(".md-status")),oe(r=>lt(r,{viewport$:t}))).subscribe()}function yi({document$:e,tablet$:t}){e.pipe(v(()=>$(".md-toggle--indeterminate")),E(r=>{r.indeterminate=!0,r.checked=!1}),oe(r=>d(r,"change").pipe(Dr(()=>r.classList.contains("md-toggle--indeterminate")),m(()=>r))),ee(t)).subscribe(([r,o])=>{r.classList.remove("md-toggle--indeterminate"),o&&(r.checked=!1)})}function fs(){return/(iPad|iPhone|iPod)/.test(navigator.userAgent)}function Ei({document$:e}){e.pipe(v(()=>$("[data-md-scrollfix]")),E(t=>t.removeAttribute("data-md-scrollfix")),b(fs),oe(t=>d(t,"touchstart").pipe(m(()=>t)))).subscribe(t=>{let r=t.scrollTop;r===0?t.scrollTop=1:r+t.offsetHeight===t.scrollHeight&&(t.scrollTop=r-1)})}function wi({viewport$:e,tablet$:t}){z([Ve("search"),t]).pipe(m(([r,o])=>r&&!o),v(r=>I(r).pipe(Ge(r?400:100))),ee(e)).subscribe(([r,{offset:{y:o}}])=>{if(r)document.body.setAttribute("data-md-scrolllock",""),document.body.style.top=`-${o}px`;else{let n=-1*parseInt(document.body.style.top,10);document.body.removeAttribute("data-md-scrolllock"),document.body.style.top="",n&&window.scrollTo(0,n)}})}Object.entries||(Object.entries=function(e){let t=[];for(let r of Object.keys(e))t.push([r,e[r]]);return t});Object.values||(Object.values=function(e){let t=[];for(let r of Object.keys(e))t.push(e[r]);return t});typeof Element!="undefined"&&(Element.prototype.scrollTo||(Element.prototype.scrollTo=function(e,t){typeof e=="object"?(this.scrollLeft=e.left,this.scrollTop=e.top):(this.scrollLeft=e,this.scrollTop=t)}),Element.prototype.replaceWith||(Element.prototype.replaceWith=function(...e){let t=this.parentNode;if(t){e.length===0&&t.removeChild(this);for(let r=e.length-1;r>=0;r--){let o=e[r];typeof o=="string"?o=document.createTextNode(o):o.parentNode&&o.parentNode.removeChild(o),r?t.insertBefore(this.previousSibling,o):t.replaceChild(o,this)}}}));function us(){return location.protocol==="file:"?wt(`${new URL("search/search_index.js",Xr.base)}`).pipe(m(()=>__index),G(1)):Ne(new URL("search/search_index.json",Xr.base))}document.documentElement.classList.remove("no-js");document.documentElement.classList.add("js");var ot=Yo(),jt=nn(),Ot=cn(jt),Zr=on(),Oe=bn(),hr=$t("(min-width: 960px)"),Si=$t("(min-width: 1220px)"),Oi=pn(),Xr=ye(),Mi=document.forms.namedItem("search")?us():Ke,eo=new g;Bn({alert$:eo});var to=new g;B("navigation.instant")&&Zn({location$:jt,viewport$:Oe,progress$:to}).subscribe(ot);var Ti;((Ti=Xr.version)==null?void 0:Ti.provider)==="mike"&&ii({document$:ot});S(jt,Ot).pipe(Ge(125)).subscribe(()=>{Je("drawer",!1),Je("search",!1)});Zr.pipe(b(({mode:e})=>e==="global")).subscribe(e=>{switch(e.type){case"p":case",":let t=fe("link[rel=prev]");typeof t!="undefined"&&pt(t);break;case"n":case".":let r=fe("link[rel=next]");typeof r!="undefined"&&pt(r);break;case"Enter":let o=Re();o instanceof HTMLLabelElement&&o.click()}});xi({viewport$:Oe,document$:ot});yi({document$:ot,tablet$:hr});Ei({document$:ot});wi({viewport$:Oe,tablet$:hr});var rt=Nn(Se("header"),{viewport$:Oe}),Ft=ot.pipe(m(()=>Se("main")),v(e=>Qn(e,{viewport$:Oe,header$:rt})),G(1)),ds=S(...ae("consent").map(e=>xn(e,{target$:Ot})),...ae("dialog").map(e=>Dn(e,{alert$:eo})),...ae("header").map(e=>zn(e,{viewport$:Oe,header$:rt,main$:Ft})),...ae("palette").map(e=>Kn(e)),...ae("progress").map(e=>Yn(e,{progress$:to})),...ae("search").map(e=>li(e,{index$:Mi,keyboard$:Zr})),...ae("source").map(e=>hi(e))),hs=C(()=>S(...ae("announce").map(e=>gn(e)),...ae("content").map(e=>Un(e,{viewport$:Oe,target$:Ot,print$:Oi})),...ae("content").map(e=>B("search.highlight")?mi(e,{index$:Mi,location$:jt}):O),...ae("header-title").map(e=>qn(e,{viewport$:Oe,header$:rt})),...ae("sidebar").map(e=>e.getAttribute("data-md-type")==="navigation"?Nr(Si,()=>Jr(e,{viewport$:Oe,header$:rt,main$:Ft})):Nr(hr,()=>Jr(e,{viewport$:Oe,header$:rt,main$:Ft}))),...ae("tabs").map(e=>bi(e,{viewport$:Oe,header$:rt})),...ae("toc").map(e=>vi(e,{viewport$:Oe,header$:rt,main$:Ft,target$:Ot})),...ae("top").map(e=>gi(e,{viewport$:Oe,header$:rt,main$:Ft,target$:Ot})))),Li=ot.pipe(v(()=>hs),Pe(ds),G(1));Li.subscribe();window.document$=ot;window.location$=jt;window.target$=Ot;window.keyboard$=Zr;window.viewport$=Oe;window.tablet$=hr;window.screen$=Si;window.print$=Oi;window.alert$=eo;window.progress$=to;window.component$=Li;})(); +//# sourceMappingURL=bundle.fe8b6f2b.min.js.map + diff --git a/v1.3.1/assets/javascripts/bundle.fe8b6f2b.min.js.map b/v1.3.1/assets/javascripts/bundle.fe8b6f2b.min.js.map new file mode 100644 index 000000000..82635852a --- /dev/null +++ b/v1.3.1/assets/javascripts/bundle.fe8b6f2b.min.js.map @@ -0,0 +1,7 @@ +{ + "version": 3, + "sources": ["node_modules/focus-visible/dist/focus-visible.js", "node_modules/clipboard/dist/clipboard.js", "node_modules/escape-html/index.js", "src/templates/assets/javascripts/bundle.ts", "node_modules/rxjs/node_modules/tslib/tslib.es6.js", "node_modules/rxjs/src/internal/util/isFunction.ts", "node_modules/rxjs/src/internal/util/createErrorClass.ts", "node_modules/rxjs/src/internal/util/UnsubscriptionError.ts", "node_modules/rxjs/src/internal/util/arrRemove.ts", "node_modules/rxjs/src/internal/Subscription.ts", "node_modules/rxjs/src/internal/config.ts", "node_modules/rxjs/src/internal/scheduler/timeoutProvider.ts", "node_modules/rxjs/src/internal/util/reportUnhandledError.ts", "node_modules/rxjs/src/internal/util/noop.ts", "node_modules/rxjs/src/internal/NotificationFactories.ts", "node_modules/rxjs/src/internal/util/errorContext.ts", "node_modules/rxjs/src/internal/Subscriber.ts", "node_modules/rxjs/src/internal/symbol/observable.ts", "node_modules/rxjs/src/internal/util/identity.ts", "node_modules/rxjs/src/internal/util/pipe.ts", "node_modules/rxjs/src/internal/Observable.ts", "node_modules/rxjs/src/internal/util/lift.ts", "node_modules/rxjs/src/internal/operators/OperatorSubscriber.ts", "node_modules/rxjs/src/internal/scheduler/animationFrameProvider.ts", "node_modules/rxjs/src/internal/util/ObjectUnsubscribedError.ts", "node_modules/rxjs/src/internal/Subject.ts", "node_modules/rxjs/src/internal/BehaviorSubject.ts", "node_modules/rxjs/src/internal/scheduler/dateTimestampProvider.ts", "node_modules/rxjs/src/internal/ReplaySubject.ts", "node_modules/rxjs/src/internal/scheduler/Action.ts", "node_modules/rxjs/src/internal/scheduler/intervalProvider.ts", "node_modules/rxjs/src/internal/scheduler/AsyncAction.ts", "node_modules/rxjs/src/internal/Scheduler.ts", "node_modules/rxjs/src/internal/scheduler/AsyncScheduler.ts", "node_modules/rxjs/src/internal/scheduler/async.ts", "node_modules/rxjs/src/internal/scheduler/QueueAction.ts", "node_modules/rxjs/src/internal/scheduler/QueueScheduler.ts", "node_modules/rxjs/src/internal/scheduler/queue.ts", "node_modules/rxjs/src/internal/scheduler/AnimationFrameAction.ts", "node_modules/rxjs/src/internal/scheduler/AnimationFrameScheduler.ts", "node_modules/rxjs/src/internal/scheduler/animationFrame.ts", "node_modules/rxjs/src/internal/observable/empty.ts", "node_modules/rxjs/src/internal/util/isScheduler.ts", "node_modules/rxjs/src/internal/util/args.ts", "node_modules/rxjs/src/internal/util/isArrayLike.ts", "node_modules/rxjs/src/internal/util/isPromise.ts", "node_modules/rxjs/src/internal/util/isInteropObservable.ts", "node_modules/rxjs/src/internal/util/isAsyncIterable.ts", "node_modules/rxjs/src/internal/util/throwUnobservableError.ts", "node_modules/rxjs/src/internal/symbol/iterator.ts", "node_modules/rxjs/src/internal/util/isIterable.ts", "node_modules/rxjs/src/internal/util/isReadableStreamLike.ts", "node_modules/rxjs/src/internal/observable/innerFrom.ts", "node_modules/rxjs/src/internal/util/executeSchedule.ts", "node_modules/rxjs/src/internal/operators/observeOn.ts", "node_modules/rxjs/src/internal/operators/subscribeOn.ts", "node_modules/rxjs/src/internal/scheduled/scheduleObservable.ts", "node_modules/rxjs/src/internal/scheduled/schedulePromise.ts", "node_modules/rxjs/src/internal/scheduled/scheduleArray.ts", "node_modules/rxjs/src/internal/scheduled/scheduleIterable.ts", "node_modules/rxjs/src/internal/scheduled/scheduleAsyncIterable.ts", "node_modules/rxjs/src/internal/scheduled/scheduleReadableStreamLike.ts", "node_modules/rxjs/src/internal/scheduled/scheduled.ts", "node_modules/rxjs/src/internal/observable/from.ts", "node_modules/rxjs/src/internal/observable/of.ts", "node_modules/rxjs/src/internal/observable/throwError.ts", "node_modules/rxjs/src/internal/util/EmptyError.ts", "node_modules/rxjs/src/internal/util/isDate.ts", "node_modules/rxjs/src/internal/operators/map.ts", "node_modules/rxjs/src/internal/util/mapOneOrManyArgs.ts", "node_modules/rxjs/src/internal/util/argsArgArrayOrObject.ts", "node_modules/rxjs/src/internal/util/createObject.ts", "node_modules/rxjs/src/internal/observable/combineLatest.ts", "node_modules/rxjs/src/internal/operators/mergeInternals.ts", "node_modules/rxjs/src/internal/operators/mergeMap.ts", "node_modules/rxjs/src/internal/operators/mergeAll.ts", "node_modules/rxjs/src/internal/operators/concatAll.ts", "node_modules/rxjs/src/internal/observable/concat.ts", "node_modules/rxjs/src/internal/observable/defer.ts", "node_modules/rxjs/src/internal/observable/fromEvent.ts", "node_modules/rxjs/src/internal/observable/fromEventPattern.ts", "node_modules/rxjs/src/internal/observable/timer.ts", "node_modules/rxjs/src/internal/observable/merge.ts", "node_modules/rxjs/src/internal/observable/never.ts", "node_modules/rxjs/src/internal/util/argsOrArgArray.ts", "node_modules/rxjs/src/internal/operators/filter.ts", "node_modules/rxjs/src/internal/observable/zip.ts", "node_modules/rxjs/src/internal/operators/audit.ts", "node_modules/rxjs/src/internal/operators/auditTime.ts", "node_modules/rxjs/src/internal/operators/bufferCount.ts", "node_modules/rxjs/src/internal/operators/catchError.ts", "node_modules/rxjs/src/internal/operators/scanInternals.ts", "node_modules/rxjs/src/internal/operators/combineLatest.ts", "node_modules/rxjs/src/internal/operators/combineLatestWith.ts", "node_modules/rxjs/src/internal/operators/debounce.ts", "node_modules/rxjs/src/internal/operators/debounceTime.ts", "node_modules/rxjs/src/internal/operators/defaultIfEmpty.ts", "node_modules/rxjs/src/internal/operators/take.ts", "node_modules/rxjs/src/internal/operators/ignoreElements.ts", "node_modules/rxjs/src/internal/operators/mapTo.ts", "node_modules/rxjs/src/internal/operators/delayWhen.ts", "node_modules/rxjs/src/internal/operators/delay.ts", "node_modules/rxjs/src/internal/operators/distinctUntilChanged.ts", "node_modules/rxjs/src/internal/operators/distinctUntilKeyChanged.ts", "node_modules/rxjs/src/internal/operators/throwIfEmpty.ts", "node_modules/rxjs/src/internal/operators/endWith.ts", "node_modules/rxjs/src/internal/operators/finalize.ts", "node_modules/rxjs/src/internal/operators/first.ts", "node_modules/rxjs/src/internal/operators/takeLast.ts", "node_modules/rxjs/src/internal/operators/merge.ts", "node_modules/rxjs/src/internal/operators/mergeWith.ts", "node_modules/rxjs/src/internal/operators/repeat.ts", "node_modules/rxjs/src/internal/operators/scan.ts", "node_modules/rxjs/src/internal/operators/share.ts", "node_modules/rxjs/src/internal/operators/shareReplay.ts", "node_modules/rxjs/src/internal/operators/skip.ts", "node_modules/rxjs/src/internal/operators/skipUntil.ts", "node_modules/rxjs/src/internal/operators/startWith.ts", "node_modules/rxjs/src/internal/operators/switchMap.ts", "node_modules/rxjs/src/internal/operators/takeUntil.ts", "node_modules/rxjs/src/internal/operators/takeWhile.ts", "node_modules/rxjs/src/internal/operators/tap.ts", "node_modules/rxjs/src/internal/operators/throttle.ts", "node_modules/rxjs/src/internal/operators/throttleTime.ts", "node_modules/rxjs/src/internal/operators/withLatestFrom.ts", "node_modules/rxjs/src/internal/operators/zip.ts", "node_modules/rxjs/src/internal/operators/zipWith.ts", "src/templates/assets/javascripts/browser/document/index.ts", "src/templates/assets/javascripts/browser/element/_/index.ts", "src/templates/assets/javascripts/browser/element/focus/index.ts", "src/templates/assets/javascripts/browser/element/hover/index.ts", "src/templates/assets/javascripts/utilities/h/index.ts", "src/templates/assets/javascripts/utilities/round/index.ts", "src/templates/assets/javascripts/browser/script/index.ts", "src/templates/assets/javascripts/browser/element/size/_/index.ts", "src/templates/assets/javascripts/browser/element/size/content/index.ts", "src/templates/assets/javascripts/browser/element/offset/_/index.ts", "src/templates/assets/javascripts/browser/element/offset/content/index.ts", "src/templates/assets/javascripts/browser/element/visibility/index.ts", "src/templates/assets/javascripts/browser/toggle/index.ts", "src/templates/assets/javascripts/browser/keyboard/index.ts", "src/templates/assets/javascripts/browser/location/_/index.ts", "src/templates/assets/javascripts/browser/location/hash/index.ts", "src/templates/assets/javascripts/browser/media/index.ts", "src/templates/assets/javascripts/browser/request/index.ts", "src/templates/assets/javascripts/browser/viewport/offset/index.ts", "src/templates/assets/javascripts/browser/viewport/size/index.ts", "src/templates/assets/javascripts/browser/viewport/_/index.ts", "src/templates/assets/javascripts/browser/viewport/at/index.ts", "src/templates/assets/javascripts/browser/worker/index.ts", "src/templates/assets/javascripts/_/index.ts", "src/templates/assets/javascripts/components/_/index.ts", "src/templates/assets/javascripts/components/announce/index.ts", "src/templates/assets/javascripts/components/consent/index.ts", "src/templates/assets/javascripts/templates/tooltip/index.tsx", "src/templates/assets/javascripts/templates/annotation/index.tsx", "src/templates/assets/javascripts/templates/clipboard/index.tsx", "src/templates/assets/javascripts/templates/search/index.tsx", "src/templates/assets/javascripts/templates/source/index.tsx", "src/templates/assets/javascripts/templates/tabbed/index.tsx", "src/templates/assets/javascripts/templates/table/index.tsx", "src/templates/assets/javascripts/templates/version/index.tsx", "src/templates/assets/javascripts/components/tooltip2/index.ts", "src/templates/assets/javascripts/components/content/annotation/_/index.ts", "src/templates/assets/javascripts/components/content/annotation/list/index.ts", "src/templates/assets/javascripts/components/content/annotation/block/index.ts", "src/templates/assets/javascripts/components/content/code/_/index.ts", "src/templates/assets/javascripts/components/content/details/index.ts", "src/templates/assets/javascripts/components/content/mermaid/index.css", "src/templates/assets/javascripts/components/content/mermaid/index.ts", "src/templates/assets/javascripts/components/content/table/index.ts", "src/templates/assets/javascripts/components/content/tabs/index.ts", "src/templates/assets/javascripts/components/content/_/index.ts", "src/templates/assets/javascripts/components/dialog/index.ts", "src/templates/assets/javascripts/components/tooltip/index.ts", "src/templates/assets/javascripts/components/header/_/index.ts", "src/templates/assets/javascripts/components/header/title/index.ts", "src/templates/assets/javascripts/components/main/index.ts", "src/templates/assets/javascripts/components/palette/index.ts", "src/templates/assets/javascripts/components/progress/index.ts", "src/templates/assets/javascripts/integrations/clipboard/index.ts", "src/templates/assets/javascripts/integrations/sitemap/index.ts", "src/templates/assets/javascripts/integrations/instant/index.ts", "src/templates/assets/javascripts/integrations/search/highlighter/index.ts", "src/templates/assets/javascripts/integrations/search/worker/message/index.ts", "src/templates/assets/javascripts/integrations/search/worker/_/index.ts", "src/templates/assets/javascripts/integrations/version/index.ts", "src/templates/assets/javascripts/components/search/query/index.ts", "src/templates/assets/javascripts/components/search/result/index.ts", "src/templates/assets/javascripts/components/search/share/index.ts", "src/templates/assets/javascripts/components/search/suggest/index.ts", "src/templates/assets/javascripts/components/search/_/index.ts", "src/templates/assets/javascripts/components/search/highlight/index.ts", "src/templates/assets/javascripts/components/sidebar/index.ts", "src/templates/assets/javascripts/components/source/facts/github/index.ts", "src/templates/assets/javascripts/components/source/facts/gitlab/index.ts", "src/templates/assets/javascripts/components/source/facts/_/index.ts", "src/templates/assets/javascripts/components/source/_/index.ts", "src/templates/assets/javascripts/components/tabs/index.ts", "src/templates/assets/javascripts/components/toc/index.ts", "src/templates/assets/javascripts/components/top/index.ts", "src/templates/assets/javascripts/patches/ellipsis/index.ts", "src/templates/assets/javascripts/patches/indeterminate/index.ts", "src/templates/assets/javascripts/patches/scrollfix/index.ts", "src/templates/assets/javascripts/patches/scrolllock/index.ts", "src/templates/assets/javascripts/polyfills/index.ts"], + "sourcesContent": ["(function (global, factory) {\n typeof exports === 'object' && typeof module !== 'undefined' ? factory() :\n typeof define === 'function' && define.amd ? define(factory) :\n (factory());\n}(this, (function () { 'use strict';\n\n /**\n * Applies the :focus-visible polyfill at the given scope.\n * A scope in this case is either the top-level Document or a Shadow Root.\n *\n * @param {(Document|ShadowRoot)} scope\n * @see https://github.com/WICG/focus-visible\n */\n function applyFocusVisiblePolyfill(scope) {\n var hadKeyboardEvent = true;\n var hadFocusVisibleRecently = false;\n var hadFocusVisibleRecentlyTimeout = null;\n\n var inputTypesAllowlist = {\n text: true,\n search: true,\n url: true,\n tel: true,\n email: true,\n password: true,\n number: true,\n date: true,\n month: true,\n week: true,\n time: true,\n datetime: true,\n 'datetime-local': true\n };\n\n /**\n * Helper function for legacy browsers and iframes which sometimes focus\n * elements like document, body, and non-interactive SVG.\n * @param {Element} el\n */\n function isValidFocusTarget(el) {\n if (\n el &&\n el !== document &&\n el.nodeName !== 'HTML' &&\n el.nodeName !== 'BODY' &&\n 'classList' in el &&\n 'contains' in el.classList\n ) {\n return true;\n }\n return false;\n }\n\n /**\n * Computes whether the given element should automatically trigger the\n * `focus-visible` class being added, i.e. whether it should always match\n * `:focus-visible` when focused.\n * @param {Element} el\n * @return {boolean}\n */\n function focusTriggersKeyboardModality(el) {\n var type = el.type;\n var tagName = el.tagName;\n\n if (tagName === 'INPUT' && inputTypesAllowlist[type] && !el.readOnly) {\n return true;\n }\n\n if (tagName === 'TEXTAREA' && !el.readOnly) {\n return true;\n }\n\n if (el.isContentEditable) {\n return true;\n }\n\n return false;\n }\n\n /**\n * Add the `focus-visible` class to the given element if it was not added by\n * the author.\n * @param {Element} el\n */\n function addFocusVisibleClass(el) {\n if (el.classList.contains('focus-visible')) {\n return;\n }\n el.classList.add('focus-visible');\n el.setAttribute('data-focus-visible-added', '');\n }\n\n /**\n * Remove the `focus-visible` class from the given element if it was not\n * originally added by the author.\n * @param {Element} el\n */\n function removeFocusVisibleClass(el) {\n if (!el.hasAttribute('data-focus-visible-added')) {\n return;\n }\n el.classList.remove('focus-visible');\n el.removeAttribute('data-focus-visible-added');\n }\n\n /**\n * If the most recent user interaction was via the keyboard;\n * and the key press did not include a meta, alt/option, or control key;\n * then the modality is keyboard. Otherwise, the modality is not keyboard.\n * Apply `focus-visible` to any current active element and keep track\n * of our keyboard modality state with `hadKeyboardEvent`.\n * @param {KeyboardEvent} e\n */\n function onKeyDown(e) {\n if (e.metaKey || e.altKey || e.ctrlKey) {\n return;\n }\n\n if (isValidFocusTarget(scope.activeElement)) {\n addFocusVisibleClass(scope.activeElement);\n }\n\n hadKeyboardEvent = true;\n }\n\n /**\n * If at any point a user clicks with a pointing device, ensure that we change\n * the modality away from keyboard.\n * This avoids the situation where a user presses a key on an already focused\n * element, and then clicks on a different element, focusing it with a\n * pointing device, while we still think we're in keyboard modality.\n * @param {Event} e\n */\n function onPointerDown(e) {\n hadKeyboardEvent = false;\n }\n\n /**\n * On `focus`, add the `focus-visible` class to the target if:\n * - the target received focus as a result of keyboard navigation, or\n * - the event target is an element that will likely require interaction\n * via the keyboard (e.g. a text box)\n * @param {Event} e\n */\n function onFocus(e) {\n // Prevent IE from focusing the document or HTML element.\n if (!isValidFocusTarget(e.target)) {\n return;\n }\n\n if (hadKeyboardEvent || focusTriggersKeyboardModality(e.target)) {\n addFocusVisibleClass(e.target);\n }\n }\n\n /**\n * On `blur`, remove the `focus-visible` class from the target.\n * @param {Event} e\n */\n function onBlur(e) {\n if (!isValidFocusTarget(e.target)) {\n return;\n }\n\n if (\n e.target.classList.contains('focus-visible') ||\n e.target.hasAttribute('data-focus-visible-added')\n ) {\n // To detect a tab/window switch, we look for a blur event followed\n // rapidly by a visibility change.\n // If we don't see a visibility change within 100ms, it's probably a\n // regular focus change.\n hadFocusVisibleRecently = true;\n window.clearTimeout(hadFocusVisibleRecentlyTimeout);\n hadFocusVisibleRecentlyTimeout = window.setTimeout(function() {\n hadFocusVisibleRecently = false;\n }, 100);\n removeFocusVisibleClass(e.target);\n }\n }\n\n /**\n * If the user changes tabs, keep track of whether or not the previously\n * focused element had .focus-visible.\n * @param {Event} e\n */\n function onVisibilityChange(e) {\n if (document.visibilityState === 'hidden') {\n // If the tab becomes active again, the browser will handle calling focus\n // on the element (Safari actually calls it twice).\n // If this tab change caused a blur on an element with focus-visible,\n // re-apply the class when the user switches back to the tab.\n if (hadFocusVisibleRecently) {\n hadKeyboardEvent = true;\n }\n addInitialPointerMoveListeners();\n }\n }\n\n /**\n * Add a group of listeners to detect usage of any pointing devices.\n * These listeners will be added when the polyfill first loads, and anytime\n * the window is blurred, so that they are active when the window regains\n * focus.\n */\n function addInitialPointerMoveListeners() {\n document.addEventListener('mousemove', onInitialPointerMove);\n document.addEventListener('mousedown', onInitialPointerMove);\n document.addEventListener('mouseup', onInitialPointerMove);\n document.addEventListener('pointermove', onInitialPointerMove);\n document.addEventListener('pointerdown', onInitialPointerMove);\n document.addEventListener('pointerup', onInitialPointerMove);\n document.addEventListener('touchmove', onInitialPointerMove);\n document.addEventListener('touchstart', onInitialPointerMove);\n document.addEventListener('touchend', onInitialPointerMove);\n }\n\n function removeInitialPointerMoveListeners() {\n document.removeEventListener('mousemove', onInitialPointerMove);\n document.removeEventListener('mousedown', onInitialPointerMove);\n document.removeEventListener('mouseup', onInitialPointerMove);\n document.removeEventListener('pointermove', onInitialPointerMove);\n document.removeEventListener('pointerdown', onInitialPointerMove);\n document.removeEventListener('pointerup', onInitialPointerMove);\n document.removeEventListener('touchmove', onInitialPointerMove);\n document.removeEventListener('touchstart', onInitialPointerMove);\n document.removeEventListener('touchend', onInitialPointerMove);\n }\n\n /**\n * When the polfyill first loads, assume the user is in keyboard modality.\n * If any event is received from a pointing device (e.g. mouse, pointer,\n * touch), turn off keyboard modality.\n * This accounts for situations where focus enters the page from the URL bar.\n * @param {Event} e\n */\n function onInitialPointerMove(e) {\n // Work around a Safari quirk that fires a mousemove on whenever the\n // window blurs, even if you're tabbing out of the page. \u00AF\\_(\u30C4)_/\u00AF\n if (e.target.nodeName && e.target.nodeName.toLowerCase() === 'html') {\n return;\n }\n\n hadKeyboardEvent = false;\n removeInitialPointerMoveListeners();\n }\n\n // For some kinds of state, we are interested in changes at the global scope\n // only. For example, global pointer input, global key presses and global\n // visibility change should affect the state at every scope:\n document.addEventListener('keydown', onKeyDown, true);\n document.addEventListener('mousedown', onPointerDown, true);\n document.addEventListener('pointerdown', onPointerDown, true);\n document.addEventListener('touchstart', onPointerDown, true);\n document.addEventListener('visibilitychange', onVisibilityChange, true);\n\n addInitialPointerMoveListeners();\n\n // For focus and blur, we specifically care about state changes in the local\n // scope. This is because focus / blur events that originate from within a\n // shadow root are not re-dispatched from the host element if it was already\n // the active element in its own scope:\n scope.addEventListener('focus', onFocus, true);\n scope.addEventListener('blur', onBlur, true);\n\n // We detect that a node is a ShadowRoot by ensuring that it is a\n // DocumentFragment and also has a host property. This check covers native\n // implementation and polyfill implementation transparently. If we only cared\n // about the native implementation, we could just check if the scope was\n // an instance of a ShadowRoot.\n if (scope.nodeType === Node.DOCUMENT_FRAGMENT_NODE && scope.host) {\n // Since a ShadowRoot is a special kind of DocumentFragment, it does not\n // have a root element to add a class to. So, we add this attribute to the\n // host element instead:\n scope.host.setAttribute('data-js-focus-visible', '');\n } else if (scope.nodeType === Node.DOCUMENT_NODE) {\n document.documentElement.classList.add('js-focus-visible');\n document.documentElement.setAttribute('data-js-focus-visible', '');\n }\n }\n\n // It is important to wrap all references to global window and document in\n // these checks to support server-side rendering use cases\n // @see https://github.com/WICG/focus-visible/issues/199\n if (typeof window !== 'undefined' && typeof document !== 'undefined') {\n // Make the polyfill helper globally available. This can be used as a signal\n // to interested libraries that wish to coordinate with the polyfill for e.g.,\n // applying the polyfill to a shadow root:\n window.applyFocusVisiblePolyfill = applyFocusVisiblePolyfill;\n\n // Notify interested libraries of the polyfill's presence, in case the\n // polyfill was loaded lazily:\n var event;\n\n try {\n event = new CustomEvent('focus-visible-polyfill-ready');\n } catch (error) {\n // IE11 does not support using CustomEvent as a constructor directly:\n event = document.createEvent('CustomEvent');\n event.initCustomEvent('focus-visible-polyfill-ready', false, false, {});\n }\n\n window.dispatchEvent(event);\n }\n\n if (typeof document !== 'undefined') {\n // Apply the polyfill to the global document, so that no JavaScript\n // coordination is required to use the polyfill in the top-level document:\n applyFocusVisiblePolyfill(document);\n }\n\n})));\n", "/*!\n * clipboard.js v2.0.11\n * https://clipboardjs.com/\n *\n * Licensed MIT \u00A9 Zeno Rocha\n */\n(function webpackUniversalModuleDefinition(root, factory) {\n\tif(typeof exports === 'object' && typeof module === 'object')\n\t\tmodule.exports = factory();\n\telse if(typeof define === 'function' && define.amd)\n\t\tdefine([], factory);\n\telse if(typeof exports === 'object')\n\t\texports[\"ClipboardJS\"] = factory();\n\telse\n\t\troot[\"ClipboardJS\"] = factory();\n})(this, function() {\nreturn /******/ (function() { // webpackBootstrap\n/******/ \tvar __webpack_modules__ = ({\n\n/***/ 686:\n/***/ (function(__unused_webpack_module, __webpack_exports__, __webpack_require__) {\n\n\"use strict\";\n\n// EXPORTS\n__webpack_require__.d(__webpack_exports__, {\n \"default\": function() { return /* binding */ clipboard; }\n});\n\n// EXTERNAL MODULE: ./node_modules/tiny-emitter/index.js\nvar tiny_emitter = __webpack_require__(279);\nvar tiny_emitter_default = /*#__PURE__*/__webpack_require__.n(tiny_emitter);\n// EXTERNAL MODULE: ./node_modules/good-listener/src/listen.js\nvar listen = __webpack_require__(370);\nvar listen_default = /*#__PURE__*/__webpack_require__.n(listen);\n// EXTERNAL MODULE: ./node_modules/select/src/select.js\nvar src_select = __webpack_require__(817);\nvar select_default = /*#__PURE__*/__webpack_require__.n(src_select);\n;// CONCATENATED MODULE: ./src/common/command.js\n/**\n * Executes a given operation type.\n * @param {String} type\n * @return {Boolean}\n */\nfunction command(type) {\n try {\n return document.execCommand(type);\n } catch (err) {\n return false;\n }\n}\n;// CONCATENATED MODULE: ./src/actions/cut.js\n\n\n/**\n * Cut action wrapper.\n * @param {String|HTMLElement} target\n * @return {String}\n */\n\nvar ClipboardActionCut = function ClipboardActionCut(target) {\n var selectedText = select_default()(target);\n command('cut');\n return selectedText;\n};\n\n/* harmony default export */ var actions_cut = (ClipboardActionCut);\n;// CONCATENATED MODULE: ./src/common/create-fake-element.js\n/**\n * Creates a fake textarea element with a value.\n * @param {String} value\n * @return {HTMLElement}\n */\nfunction createFakeElement(value) {\n var isRTL = document.documentElement.getAttribute('dir') === 'rtl';\n var fakeElement = document.createElement('textarea'); // Prevent zooming on iOS\n\n fakeElement.style.fontSize = '12pt'; // Reset box model\n\n fakeElement.style.border = '0';\n fakeElement.style.padding = '0';\n fakeElement.style.margin = '0'; // Move element out of screen horizontally\n\n fakeElement.style.position = 'absolute';\n fakeElement.style[isRTL ? 'right' : 'left'] = '-9999px'; // Move element to the same position vertically\n\n var yPosition = window.pageYOffset || document.documentElement.scrollTop;\n fakeElement.style.top = \"\".concat(yPosition, \"px\");\n fakeElement.setAttribute('readonly', '');\n fakeElement.value = value;\n return fakeElement;\n}\n;// CONCATENATED MODULE: ./src/actions/copy.js\n\n\n\n/**\n * Create fake copy action wrapper using a fake element.\n * @param {String} target\n * @param {Object} options\n * @return {String}\n */\n\nvar fakeCopyAction = function fakeCopyAction(value, options) {\n var fakeElement = createFakeElement(value);\n options.container.appendChild(fakeElement);\n var selectedText = select_default()(fakeElement);\n command('copy');\n fakeElement.remove();\n return selectedText;\n};\n/**\n * Copy action wrapper.\n * @param {String|HTMLElement} target\n * @param {Object} options\n * @return {String}\n */\n\n\nvar ClipboardActionCopy = function ClipboardActionCopy(target) {\n var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {\n container: document.body\n };\n var selectedText = '';\n\n if (typeof target === 'string') {\n selectedText = fakeCopyAction(target, options);\n } else if (target instanceof HTMLInputElement && !['text', 'search', 'url', 'tel', 'password'].includes(target === null || target === void 0 ? void 0 : target.type)) {\n // If input type doesn't support `setSelectionRange`. Simulate it. https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange\n selectedText = fakeCopyAction(target.value, options);\n } else {\n selectedText = select_default()(target);\n command('copy');\n }\n\n return selectedText;\n};\n\n/* harmony default export */ var actions_copy = (ClipboardActionCopy);\n;// CONCATENATED MODULE: ./src/actions/default.js\nfunction _typeof(obj) { \"@babel/helpers - typeof\"; if (typeof Symbol === \"function\" && typeof Symbol.iterator === \"symbol\") { _typeof = function _typeof(obj) { return typeof obj; }; } else { _typeof = function _typeof(obj) { return obj && typeof Symbol === \"function\" && obj.constructor === Symbol && obj !== Symbol.prototype ? \"symbol\" : typeof obj; }; } return _typeof(obj); }\n\n\n\n/**\n * Inner function which performs selection from either `text` or `target`\n * properties and then executes copy or cut operations.\n * @param {Object} options\n */\n\nvar ClipboardActionDefault = function ClipboardActionDefault() {\n var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};\n // Defines base properties passed from constructor.\n var _options$action = options.action,\n action = _options$action === void 0 ? 'copy' : _options$action,\n container = options.container,\n target = options.target,\n text = options.text; // Sets the `action` to be performed which can be either 'copy' or 'cut'.\n\n if (action !== 'copy' && action !== 'cut') {\n throw new Error('Invalid \"action\" value, use either \"copy\" or \"cut\"');\n } // Sets the `target` property using an element that will be have its content copied.\n\n\n if (target !== undefined) {\n if (target && _typeof(target) === 'object' && target.nodeType === 1) {\n if (action === 'copy' && target.hasAttribute('disabled')) {\n throw new Error('Invalid \"target\" attribute. Please use \"readonly\" instead of \"disabled\" attribute');\n }\n\n if (action === 'cut' && (target.hasAttribute('readonly') || target.hasAttribute('disabled'))) {\n throw new Error('Invalid \"target\" attribute. You can\\'t cut text from elements with \"readonly\" or \"disabled\" attributes');\n }\n } else {\n throw new Error('Invalid \"target\" value, use a valid Element');\n }\n } // Define selection strategy based on `text` property.\n\n\n if (text) {\n return actions_copy(text, {\n container: container\n });\n } // Defines which selection strategy based on `target` property.\n\n\n if (target) {\n return action === 'cut' ? actions_cut(target) : actions_copy(target, {\n container: container\n });\n }\n};\n\n/* harmony default export */ var actions_default = (ClipboardActionDefault);\n;// CONCATENATED MODULE: ./src/clipboard.js\nfunction clipboard_typeof(obj) { \"@babel/helpers - typeof\"; if (typeof Symbol === \"function\" && typeof Symbol.iterator === \"symbol\") { clipboard_typeof = function _typeof(obj) { return typeof obj; }; } else { clipboard_typeof = function _typeof(obj) { return obj && typeof Symbol === \"function\" && obj.constructor === Symbol && obj !== Symbol.prototype ? \"symbol\" : typeof obj; }; } return clipboard_typeof(obj); }\n\nfunction _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError(\"Cannot call a class as a function\"); } }\n\nfunction _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if (\"value\" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } }\n\nfunction _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); return Constructor; }\n\nfunction _inherits(subClass, superClass) { if (typeof superClass !== \"function\" && superClass !== null) { throw new TypeError(\"Super expression must either be null or a function\"); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, writable: true, configurable: true } }); if (superClass) _setPrototypeOf(subClass, superClass); }\n\nfunction _setPrototypeOf(o, p) { _setPrototypeOf = Object.setPrototypeOf || function _setPrototypeOf(o, p) { o.__proto__ = p; return o; }; return _setPrototypeOf(o, p); }\n\nfunction _createSuper(Derived) { var hasNativeReflectConstruct = _isNativeReflectConstruct(); return function _createSuperInternal() { var Super = _getPrototypeOf(Derived), result; if (hasNativeReflectConstruct) { var NewTarget = _getPrototypeOf(this).constructor; result = Reflect.construct(Super, arguments, NewTarget); } else { result = Super.apply(this, arguments); } return _possibleConstructorReturn(this, result); }; }\n\nfunction _possibleConstructorReturn(self, call) { if (call && (clipboard_typeof(call) === \"object\" || typeof call === \"function\")) { return call; } return _assertThisInitialized(self); }\n\nfunction _assertThisInitialized(self) { if (self === void 0) { throw new ReferenceError(\"this hasn't been initialised - super() hasn't been called\"); } return self; }\n\nfunction _isNativeReflectConstruct() { if (typeof Reflect === \"undefined\" || !Reflect.construct) return false; if (Reflect.construct.sham) return false; if (typeof Proxy === \"function\") return true; try { Date.prototype.toString.call(Reflect.construct(Date, [], function () {})); return true; } catch (e) { return false; } }\n\nfunction _getPrototypeOf(o) { _getPrototypeOf = Object.setPrototypeOf ? Object.getPrototypeOf : function _getPrototypeOf(o) { return o.__proto__ || Object.getPrototypeOf(o); }; return _getPrototypeOf(o); }\n\n\n\n\n\n\n/**\n * Helper function to retrieve attribute value.\n * @param {String} suffix\n * @param {Element} element\n */\n\nfunction getAttributeValue(suffix, element) {\n var attribute = \"data-clipboard-\".concat(suffix);\n\n if (!element.hasAttribute(attribute)) {\n return;\n }\n\n return element.getAttribute(attribute);\n}\n/**\n * Base class which takes one or more elements, adds event listeners to them,\n * and instantiates a new `ClipboardAction` on each click.\n */\n\n\nvar Clipboard = /*#__PURE__*/function (_Emitter) {\n _inherits(Clipboard, _Emitter);\n\n var _super = _createSuper(Clipboard);\n\n /**\n * @param {String|HTMLElement|HTMLCollection|NodeList} trigger\n * @param {Object} options\n */\n function Clipboard(trigger, options) {\n var _this;\n\n _classCallCheck(this, Clipboard);\n\n _this = _super.call(this);\n\n _this.resolveOptions(options);\n\n _this.listenClick(trigger);\n\n return _this;\n }\n /**\n * Defines if attributes would be resolved using internal setter functions\n * or custom functions that were passed in the constructor.\n * @param {Object} options\n */\n\n\n _createClass(Clipboard, [{\n key: \"resolveOptions\",\n value: function resolveOptions() {\n var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};\n this.action = typeof options.action === 'function' ? options.action : this.defaultAction;\n this.target = typeof options.target === 'function' ? options.target : this.defaultTarget;\n this.text = typeof options.text === 'function' ? options.text : this.defaultText;\n this.container = clipboard_typeof(options.container) === 'object' ? options.container : document.body;\n }\n /**\n * Adds a click event listener to the passed trigger.\n * @param {String|HTMLElement|HTMLCollection|NodeList} trigger\n */\n\n }, {\n key: \"listenClick\",\n value: function listenClick(trigger) {\n var _this2 = this;\n\n this.listener = listen_default()(trigger, 'click', function (e) {\n return _this2.onClick(e);\n });\n }\n /**\n * Defines a new `ClipboardAction` on each click event.\n * @param {Event} e\n */\n\n }, {\n key: \"onClick\",\n value: function onClick(e) {\n var trigger = e.delegateTarget || e.currentTarget;\n var action = this.action(trigger) || 'copy';\n var text = actions_default({\n action: action,\n container: this.container,\n target: this.target(trigger),\n text: this.text(trigger)\n }); // Fires an event based on the copy operation result.\n\n this.emit(text ? 'success' : 'error', {\n action: action,\n text: text,\n trigger: trigger,\n clearSelection: function clearSelection() {\n if (trigger) {\n trigger.focus();\n }\n\n window.getSelection().removeAllRanges();\n }\n });\n }\n /**\n * Default `action` lookup function.\n * @param {Element} trigger\n */\n\n }, {\n key: \"defaultAction\",\n value: function defaultAction(trigger) {\n return getAttributeValue('action', trigger);\n }\n /**\n * Default `target` lookup function.\n * @param {Element} trigger\n */\n\n }, {\n key: \"defaultTarget\",\n value: function defaultTarget(trigger) {\n var selector = getAttributeValue('target', trigger);\n\n if (selector) {\n return document.querySelector(selector);\n }\n }\n /**\n * Allow fire programmatically a copy action\n * @param {String|HTMLElement} target\n * @param {Object} options\n * @returns Text copied.\n */\n\n }, {\n key: \"defaultText\",\n\n /**\n * Default `text` lookup function.\n * @param {Element} trigger\n */\n value: function defaultText(trigger) {\n return getAttributeValue('text', trigger);\n }\n /**\n * Destroy lifecycle.\n */\n\n }, {\n key: \"destroy\",\n value: function destroy() {\n this.listener.destroy();\n }\n }], [{\n key: \"copy\",\n value: function copy(target) {\n var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {\n container: document.body\n };\n return actions_copy(target, options);\n }\n /**\n * Allow fire programmatically a cut action\n * @param {String|HTMLElement} target\n * @returns Text cutted.\n */\n\n }, {\n key: \"cut\",\n value: function cut(target) {\n return actions_cut(target);\n }\n /**\n * Returns the support of the given action, or all actions if no action is\n * given.\n * @param {String} [action]\n */\n\n }, {\n key: \"isSupported\",\n value: function isSupported() {\n var action = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : ['copy', 'cut'];\n var actions = typeof action === 'string' ? [action] : action;\n var support = !!document.queryCommandSupported;\n actions.forEach(function (action) {\n support = support && !!document.queryCommandSupported(action);\n });\n return support;\n }\n }]);\n\n return Clipboard;\n}((tiny_emitter_default()));\n\n/* harmony default export */ var clipboard = (Clipboard);\n\n/***/ }),\n\n/***/ 828:\n/***/ (function(module) {\n\nvar DOCUMENT_NODE_TYPE = 9;\n\n/**\n * A polyfill for Element.matches()\n */\nif (typeof Element !== 'undefined' && !Element.prototype.matches) {\n var proto = Element.prototype;\n\n proto.matches = proto.matchesSelector ||\n proto.mozMatchesSelector ||\n proto.msMatchesSelector ||\n proto.oMatchesSelector ||\n proto.webkitMatchesSelector;\n}\n\n/**\n * Finds the closest parent that matches a selector.\n *\n * @param {Element} element\n * @param {String} selector\n * @return {Function}\n */\nfunction closest (element, selector) {\n while (element && element.nodeType !== DOCUMENT_NODE_TYPE) {\n if (typeof element.matches === 'function' &&\n element.matches(selector)) {\n return element;\n }\n element = element.parentNode;\n }\n}\n\nmodule.exports = closest;\n\n\n/***/ }),\n\n/***/ 438:\n/***/ (function(module, __unused_webpack_exports, __webpack_require__) {\n\nvar closest = __webpack_require__(828);\n\n/**\n * Delegates event to a selector.\n *\n * @param {Element} element\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @param {Boolean} useCapture\n * @return {Object}\n */\nfunction _delegate(element, selector, type, callback, useCapture) {\n var listenerFn = listener.apply(this, arguments);\n\n element.addEventListener(type, listenerFn, useCapture);\n\n return {\n destroy: function() {\n element.removeEventListener(type, listenerFn, useCapture);\n }\n }\n}\n\n/**\n * Delegates event to a selector.\n *\n * @param {Element|String|Array} [elements]\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @param {Boolean} useCapture\n * @return {Object}\n */\nfunction delegate(elements, selector, type, callback, useCapture) {\n // Handle the regular Element usage\n if (typeof elements.addEventListener === 'function') {\n return _delegate.apply(null, arguments);\n }\n\n // Handle Element-less usage, it defaults to global delegation\n if (typeof type === 'function') {\n // Use `document` as the first parameter, then apply arguments\n // This is a short way to .unshift `arguments` without running into deoptimizations\n return _delegate.bind(null, document).apply(null, arguments);\n }\n\n // Handle Selector-based usage\n if (typeof elements === 'string') {\n elements = document.querySelectorAll(elements);\n }\n\n // Handle Array-like based usage\n return Array.prototype.map.call(elements, function (element) {\n return _delegate(element, selector, type, callback, useCapture);\n });\n}\n\n/**\n * Finds closest match and invokes callback.\n *\n * @param {Element} element\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @return {Function}\n */\nfunction listener(element, selector, type, callback) {\n return function(e) {\n e.delegateTarget = closest(e.target, selector);\n\n if (e.delegateTarget) {\n callback.call(element, e);\n }\n }\n}\n\nmodule.exports = delegate;\n\n\n/***/ }),\n\n/***/ 879:\n/***/ (function(__unused_webpack_module, exports) {\n\n/**\n * Check if argument is a HTML element.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.node = function(value) {\n return value !== undefined\n && value instanceof HTMLElement\n && value.nodeType === 1;\n};\n\n/**\n * Check if argument is a list of HTML elements.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.nodeList = function(value) {\n var type = Object.prototype.toString.call(value);\n\n return value !== undefined\n && (type === '[object NodeList]' || type === '[object HTMLCollection]')\n && ('length' in value)\n && (value.length === 0 || exports.node(value[0]));\n};\n\n/**\n * Check if argument is a string.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.string = function(value) {\n return typeof value === 'string'\n || value instanceof String;\n};\n\n/**\n * Check if argument is a function.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.fn = function(value) {\n var type = Object.prototype.toString.call(value);\n\n return type === '[object Function]';\n};\n\n\n/***/ }),\n\n/***/ 370:\n/***/ (function(module, __unused_webpack_exports, __webpack_require__) {\n\nvar is = __webpack_require__(879);\nvar delegate = __webpack_require__(438);\n\n/**\n * Validates all params and calls the right\n * listener function based on its target type.\n *\n * @param {String|HTMLElement|HTMLCollection|NodeList} target\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listen(target, type, callback) {\n if (!target && !type && !callback) {\n throw new Error('Missing required arguments');\n }\n\n if (!is.string(type)) {\n throw new TypeError('Second argument must be a String');\n }\n\n if (!is.fn(callback)) {\n throw new TypeError('Third argument must be a Function');\n }\n\n if (is.node(target)) {\n return listenNode(target, type, callback);\n }\n else if (is.nodeList(target)) {\n return listenNodeList(target, type, callback);\n }\n else if (is.string(target)) {\n return listenSelector(target, type, callback);\n }\n else {\n throw new TypeError('First argument must be a String, HTMLElement, HTMLCollection, or NodeList');\n }\n}\n\n/**\n * Adds an event listener to a HTML element\n * and returns a remove listener function.\n *\n * @param {HTMLElement} node\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenNode(node, type, callback) {\n node.addEventListener(type, callback);\n\n return {\n destroy: function() {\n node.removeEventListener(type, callback);\n }\n }\n}\n\n/**\n * Add an event listener to a list of HTML elements\n * and returns a remove listener function.\n *\n * @param {NodeList|HTMLCollection} nodeList\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenNodeList(nodeList, type, callback) {\n Array.prototype.forEach.call(nodeList, function(node) {\n node.addEventListener(type, callback);\n });\n\n return {\n destroy: function() {\n Array.prototype.forEach.call(nodeList, function(node) {\n node.removeEventListener(type, callback);\n });\n }\n }\n}\n\n/**\n * Add an event listener to a selector\n * and returns a remove listener function.\n *\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenSelector(selector, type, callback) {\n return delegate(document.body, selector, type, callback);\n}\n\nmodule.exports = listen;\n\n\n/***/ }),\n\n/***/ 817:\n/***/ (function(module) {\n\nfunction select(element) {\n var selectedText;\n\n if (element.nodeName === 'SELECT') {\n element.focus();\n\n selectedText = element.value;\n }\n else if (element.nodeName === 'INPUT' || element.nodeName === 'TEXTAREA') {\n var isReadOnly = element.hasAttribute('readonly');\n\n if (!isReadOnly) {\n element.setAttribute('readonly', '');\n }\n\n element.select();\n element.setSelectionRange(0, element.value.length);\n\n if (!isReadOnly) {\n element.removeAttribute('readonly');\n }\n\n selectedText = element.value;\n }\n else {\n if (element.hasAttribute('contenteditable')) {\n element.focus();\n }\n\n var selection = window.getSelection();\n var range = document.createRange();\n\n range.selectNodeContents(element);\n selection.removeAllRanges();\n selection.addRange(range);\n\n selectedText = selection.toString();\n }\n\n return selectedText;\n}\n\nmodule.exports = select;\n\n\n/***/ }),\n\n/***/ 279:\n/***/ (function(module) {\n\nfunction E () {\n // Keep this empty so it's easier to inherit from\n // (via https://github.com/lipsmack from https://github.com/scottcorgan/tiny-emitter/issues/3)\n}\n\nE.prototype = {\n on: function (name, callback, ctx) {\n var e = this.e || (this.e = {});\n\n (e[name] || (e[name] = [])).push({\n fn: callback,\n ctx: ctx\n });\n\n return this;\n },\n\n once: function (name, callback, ctx) {\n var self = this;\n function listener () {\n self.off(name, listener);\n callback.apply(ctx, arguments);\n };\n\n listener._ = callback\n return this.on(name, listener, ctx);\n },\n\n emit: function (name) {\n var data = [].slice.call(arguments, 1);\n var evtArr = ((this.e || (this.e = {}))[name] || []).slice();\n var i = 0;\n var len = evtArr.length;\n\n for (i; i < len; i++) {\n evtArr[i].fn.apply(evtArr[i].ctx, data);\n }\n\n return this;\n },\n\n off: function (name, callback) {\n var e = this.e || (this.e = {});\n var evts = e[name];\n var liveEvents = [];\n\n if (evts && callback) {\n for (var i = 0, len = evts.length; i < len; i++) {\n if (evts[i].fn !== callback && evts[i].fn._ !== callback)\n liveEvents.push(evts[i]);\n }\n }\n\n // Remove event from queue to prevent memory leak\n // Suggested by https://github.com/lazd\n // Ref: https://github.com/scottcorgan/tiny-emitter/commit/c6ebfaa9bc973b33d110a84a307742b7cf94c953#commitcomment-5024910\n\n (liveEvents.length)\n ? e[name] = liveEvents\n : delete e[name];\n\n return this;\n }\n};\n\nmodule.exports = E;\nmodule.exports.TinyEmitter = E;\n\n\n/***/ })\n\n/******/ \t});\n/************************************************************************/\n/******/ \t// The module cache\n/******/ \tvar __webpack_module_cache__ = {};\n/******/ \t\n/******/ \t// The require function\n/******/ \tfunction __webpack_require__(moduleId) {\n/******/ \t\t// Check if module is in cache\n/******/ \t\tif(__webpack_module_cache__[moduleId]) {\n/******/ \t\t\treturn __webpack_module_cache__[moduleId].exports;\n/******/ \t\t}\n/******/ \t\t// Create a new module (and put it into the cache)\n/******/ \t\tvar module = __webpack_module_cache__[moduleId] = {\n/******/ \t\t\t// no module.id needed\n/******/ \t\t\t// no module.loaded needed\n/******/ \t\t\texports: {}\n/******/ \t\t};\n/******/ \t\n/******/ \t\t// Execute the module function\n/******/ \t\t__webpack_modules__[moduleId](module, module.exports, __webpack_require__);\n/******/ \t\n/******/ \t\t// Return the exports of the module\n/******/ \t\treturn module.exports;\n/******/ \t}\n/******/ \t\n/************************************************************************/\n/******/ \t/* webpack/runtime/compat get default export */\n/******/ \t!function() {\n/******/ \t\t// getDefaultExport function for compatibility with non-harmony modules\n/******/ \t\t__webpack_require__.n = function(module) {\n/******/ \t\t\tvar getter = module && module.__esModule ?\n/******/ \t\t\t\tfunction() { return module['default']; } :\n/******/ \t\t\t\tfunction() { return module; };\n/******/ \t\t\t__webpack_require__.d(getter, { a: getter });\n/******/ \t\t\treturn getter;\n/******/ \t\t};\n/******/ \t}();\n/******/ \t\n/******/ \t/* webpack/runtime/define property getters */\n/******/ \t!function() {\n/******/ \t\t// define getter functions for harmony exports\n/******/ \t\t__webpack_require__.d = function(exports, definition) {\n/******/ \t\t\tfor(var key in definition) {\n/******/ \t\t\t\tif(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n/******/ \t\t\t\t\tObject.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n/******/ \t\t\t\t}\n/******/ \t\t\t}\n/******/ \t\t};\n/******/ \t}();\n/******/ \t\n/******/ \t/* webpack/runtime/hasOwnProperty shorthand */\n/******/ \t!function() {\n/******/ \t\t__webpack_require__.o = function(obj, prop) { return Object.prototype.hasOwnProperty.call(obj, prop); }\n/******/ \t}();\n/******/ \t\n/************************************************************************/\n/******/ \t// module exports must be returned from runtime so entry inlining is disabled\n/******/ \t// startup\n/******/ \t// Load entry module and return exports\n/******/ \treturn __webpack_require__(686);\n/******/ })()\n.default;\n});", "/*!\n * escape-html\n * Copyright(c) 2012-2013 TJ Holowaychuk\n * Copyright(c) 2015 Andreas Lubbe\n * Copyright(c) 2015 Tiancheng \"Timothy\" Gu\n * MIT Licensed\n */\n\n'use strict';\n\n/**\n * Module variables.\n * @private\n */\n\nvar matchHtmlRegExp = /[\"'&<>]/;\n\n/**\n * Module exports.\n * @public\n */\n\nmodule.exports = escapeHtml;\n\n/**\n * Escape special characters in the given string of html.\n *\n * @param {string} string The string to escape for inserting into HTML\n * @return {string}\n * @public\n */\n\nfunction escapeHtml(string) {\n var str = '' + string;\n var match = matchHtmlRegExp.exec(str);\n\n if (!match) {\n return str;\n }\n\n var escape;\n var html = '';\n var index = 0;\n var lastIndex = 0;\n\n for (index = match.index; index < str.length; index++) {\n switch (str.charCodeAt(index)) {\n case 34: // \"\n escape = '"';\n break;\n case 38: // &\n escape = '&';\n break;\n case 39: // '\n escape = ''';\n break;\n case 60: // <\n escape = '<';\n break;\n case 62: // >\n escape = '>';\n break;\n default:\n continue;\n }\n\n if (lastIndex !== index) {\n html += str.substring(lastIndex, index);\n }\n\n lastIndex = index + 1;\n html += escape;\n }\n\n return lastIndex !== index\n ? html + str.substring(lastIndex, index)\n : html;\n}\n", "/*\n * Copyright (c) 2016-2024 Martin Donath \n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to\n * deal in the Software without restriction, including without limitation the\n * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or\n * sell copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in\n * all copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\n * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS\n * IN THE SOFTWARE.\n */\n\nimport \"focus-visible\"\n\nimport {\n EMPTY,\n NEVER,\n Observable,\n Subject,\n defer,\n delay,\n filter,\n map,\n merge,\n mergeWith,\n shareReplay,\n switchMap\n} from \"rxjs\"\n\nimport { configuration, feature } from \"./_\"\nimport {\n at,\n getActiveElement,\n getOptionalElement,\n requestJSON,\n setLocation,\n setToggle,\n watchDocument,\n watchKeyboard,\n watchLocation,\n watchLocationTarget,\n watchMedia,\n watchPrint,\n watchScript,\n watchViewport\n} from \"./browser\"\nimport {\n getComponentElement,\n getComponentElements,\n mountAnnounce,\n mountBackToTop,\n mountConsent,\n mountContent,\n mountDialog,\n mountHeader,\n mountHeaderTitle,\n mountPalette,\n mountProgress,\n mountSearch,\n mountSearchHiglight,\n mountSidebar,\n mountSource,\n mountTableOfContents,\n mountTabs,\n watchHeader,\n watchMain\n} from \"./components\"\nimport {\n SearchIndex,\n setupClipboardJS,\n setupInstantNavigation,\n setupVersionSelector\n} from \"./integrations\"\nimport {\n patchEllipsis,\n patchIndeterminate,\n patchScrollfix,\n patchScrolllock\n} from \"./patches\"\nimport \"./polyfills\"\n\n/* ----------------------------------------------------------------------------\n * Functions - @todo refactor\n * ------------------------------------------------------------------------- */\n\n/**\n * Fetch search index\n *\n * @returns Search index observable\n */\nfunction fetchSearchIndex(): Observable {\n if (location.protocol === \"file:\") {\n return watchScript(\n `${new URL(\"search/search_index.js\", config.base)}`\n )\n .pipe(\n // @ts-ignore - @todo fix typings\n map(() => __index),\n shareReplay(1)\n )\n } else {\n return requestJSON(\n new URL(\"search/search_index.json\", config.base)\n )\n }\n}\n\n/* ----------------------------------------------------------------------------\n * Application\n * ------------------------------------------------------------------------- */\n\n/* Yay, JavaScript is available */\ndocument.documentElement.classList.remove(\"no-js\")\ndocument.documentElement.classList.add(\"js\")\n\n/* Set up navigation observables and subjects */\nconst document$ = watchDocument()\nconst location$ = watchLocation()\nconst target$ = watchLocationTarget(location$)\nconst keyboard$ = watchKeyboard()\n\n/* Set up media observables */\nconst viewport$ = watchViewport()\nconst tablet$ = watchMedia(\"(min-width: 960px)\")\nconst screen$ = watchMedia(\"(min-width: 1220px)\")\nconst print$ = watchPrint()\n\n/* Retrieve search index, if search is enabled */\nconst config = configuration()\nconst index$ = document.forms.namedItem(\"search\")\n ? fetchSearchIndex()\n : NEVER\n\n/* Set up Clipboard.js integration */\nconst alert$ = new Subject()\nsetupClipboardJS({ alert$ })\n\n/* Set up progress indicator */\nconst progress$ = new Subject()\n\n/* Set up instant navigation, if enabled */\nif (feature(\"navigation.instant\"))\n setupInstantNavigation({ location$, viewport$, progress$ })\n .subscribe(document$)\n\n/* Set up version selector */\nif (config.version?.provider === \"mike\")\n setupVersionSelector({ document$ })\n\n/* Always close drawer and search on navigation */\nmerge(location$, target$)\n .pipe(\n delay(125)\n )\n .subscribe(() => {\n setToggle(\"drawer\", false)\n setToggle(\"search\", false)\n })\n\n/* Set up global keyboard handlers */\nkeyboard$\n .pipe(\n filter(({ mode }) => mode === \"global\")\n )\n .subscribe(key => {\n switch (key.type) {\n\n /* Go to previous page */\n case \"p\":\n case \",\":\n const prev = getOptionalElement(\"link[rel=prev]\")\n if (typeof prev !== \"undefined\")\n setLocation(prev)\n break\n\n /* Go to next page */\n case \"n\":\n case \".\":\n const next = getOptionalElement(\"link[rel=next]\")\n if (typeof next !== \"undefined\")\n setLocation(next)\n break\n\n /* Expand navigation, see https://bit.ly/3ZjG5io */\n case \"Enter\":\n const active = getActiveElement()\n if (active instanceof HTMLLabelElement)\n active.click()\n }\n })\n\n/* Set up patches */\npatchEllipsis({ viewport$, document$ })\npatchIndeterminate({ document$, tablet$ })\npatchScrollfix({ document$ })\npatchScrolllock({ viewport$, tablet$ })\n\n/* Set up header and main area observable */\nconst header$ = watchHeader(getComponentElement(\"header\"), { viewport$ })\nconst main$ = document$\n .pipe(\n map(() => getComponentElement(\"main\")),\n switchMap(el => watchMain(el, { viewport$, header$ })),\n shareReplay(1)\n )\n\n/* Set up control component observables */\nconst control$ = merge(\n\n /* Consent */\n ...getComponentElements(\"consent\")\n .map(el => mountConsent(el, { target$ })),\n\n /* Dialog */\n ...getComponentElements(\"dialog\")\n .map(el => mountDialog(el, { alert$ })),\n\n /* Header */\n ...getComponentElements(\"header\")\n .map(el => mountHeader(el, { viewport$, header$, main$ })),\n\n /* Color palette */\n ...getComponentElements(\"palette\")\n .map(el => mountPalette(el)),\n\n /* Progress bar */\n ...getComponentElements(\"progress\")\n .map(el => mountProgress(el, { progress$ })),\n\n /* Search */\n ...getComponentElements(\"search\")\n .map(el => mountSearch(el, { index$, keyboard$ })),\n\n /* Repository information */\n ...getComponentElements(\"source\")\n .map(el => mountSource(el))\n)\n\n/* Set up content component observables */\nconst content$ = defer(() => merge(\n\n /* Announcement bar */\n ...getComponentElements(\"announce\")\n .map(el => mountAnnounce(el)),\n\n /* Content */\n ...getComponentElements(\"content\")\n .map(el => mountContent(el, { viewport$, target$, print$ })),\n\n /* Search highlighting */\n ...getComponentElements(\"content\")\n .map(el => feature(\"search.highlight\")\n ? mountSearchHiglight(el, { index$, location$ })\n : EMPTY\n ),\n\n /* Header title */\n ...getComponentElements(\"header-title\")\n .map(el => mountHeaderTitle(el, { viewport$, header$ })),\n\n /* Sidebar */\n ...getComponentElements(\"sidebar\")\n .map(el => el.getAttribute(\"data-md-type\") === \"navigation\"\n ? at(screen$, () => mountSidebar(el, { viewport$, header$, main$ }))\n : at(tablet$, () => mountSidebar(el, { viewport$, header$, main$ }))\n ),\n\n /* Navigation tabs */\n ...getComponentElements(\"tabs\")\n .map(el => mountTabs(el, { viewport$, header$ })),\n\n /* Table of contents */\n ...getComponentElements(\"toc\")\n .map(el => mountTableOfContents(el, {\n viewport$, header$, main$, target$\n })),\n\n /* Back-to-top button */\n ...getComponentElements(\"top\")\n .map(el => mountBackToTop(el, { viewport$, header$, main$, target$ }))\n))\n\n/* Set up component observables */\nconst component$ = document$\n .pipe(\n switchMap(() => content$),\n mergeWith(control$),\n shareReplay(1)\n )\n\n/* Subscribe to all components */\ncomponent$.subscribe()\n\n/* ----------------------------------------------------------------------------\n * Exports\n * ------------------------------------------------------------------------- */\n\nwindow.document$ = document$ /* Document observable */\nwindow.location$ = location$ /* Location subject */\nwindow.target$ = target$ /* Location target observable */\nwindow.keyboard$ = keyboard$ /* Keyboard observable */\nwindow.viewport$ = viewport$ /* Viewport observable */\nwindow.tablet$ = tablet$ /* Media tablet observable */\nwindow.screen$ = screen$ /* Media screen observable */\nwindow.print$ = print$ /* Media print observable */\nwindow.alert$ = alert$ /* Alert subject */\nwindow.progress$ = progress$ /* Progress indicator subject */\nwindow.component$ = component$ /* Component observable */\n", "/*! *****************************************************************************\r\nCopyright (c) Microsoft Corporation.\r\n\r\nPermission to use, copy, modify, and/or distribute this software for any\r\npurpose with or without fee is hereby granted.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH\r\nREGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY\r\nAND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,\r\nINDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM\r\nLOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR\r\nOTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR\r\nPERFORMANCE OF THIS SOFTWARE.\r\n***************************************************************************** */\r\n/* global Reflect, Promise */\r\n\r\nvar extendStatics = function(d, b) {\r\n extendStatics = Object.setPrototypeOf ||\r\n ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||\r\n function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };\r\n return extendStatics(d, b);\r\n};\r\n\r\nexport function __extends(d, b) {\r\n if (typeof b !== \"function\" && b !== null)\r\n throw new TypeError(\"Class extends value \" + String(b) + \" is not a constructor or null\");\r\n extendStatics(d, b);\r\n function __() { this.constructor = d; }\r\n d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());\r\n}\r\n\r\nexport var __assign = function() {\r\n __assign = Object.assign || function __assign(t) {\r\n for (var s, i = 1, n = arguments.length; i < n; i++) {\r\n s = arguments[i];\r\n for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p)) t[p] = s[p];\r\n }\r\n return t;\r\n }\r\n return __assign.apply(this, arguments);\r\n}\r\n\r\nexport function __rest(s, e) {\r\n var t = {};\r\n for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)\r\n t[p] = s[p];\r\n if (s != null && typeof Object.getOwnPropertySymbols === \"function\")\r\n for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {\r\n if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))\r\n t[p[i]] = s[p[i]];\r\n }\r\n return t;\r\n}\r\n\r\nexport function __decorate(decorators, target, key, desc) {\r\n var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;\r\n if (typeof Reflect === \"object\" && typeof Reflect.decorate === \"function\") r = Reflect.decorate(decorators, target, key, desc);\r\n else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;\r\n return c > 3 && r && Object.defineProperty(target, key, r), r;\r\n}\r\n\r\nexport function __param(paramIndex, decorator) {\r\n return function (target, key) { decorator(target, key, paramIndex); }\r\n}\r\n\r\nexport function __metadata(metadataKey, metadataValue) {\r\n if (typeof Reflect === \"object\" && typeof Reflect.metadata === \"function\") return Reflect.metadata(metadataKey, metadataValue);\r\n}\r\n\r\nexport function __awaiter(thisArg, _arguments, P, generator) {\r\n function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }\r\n return new (P || (P = Promise))(function (resolve, reject) {\r\n function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }\r\n function rejected(value) { try { step(generator[\"throw\"](value)); } catch (e) { reject(e); } }\r\n function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }\r\n step((generator = generator.apply(thisArg, _arguments || [])).next());\r\n });\r\n}\r\n\r\nexport function __generator(thisArg, body) {\r\n var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;\r\n return g = { next: verb(0), \"throw\": verb(1), \"return\": verb(2) }, typeof Symbol === \"function\" && (g[Symbol.iterator] = function() { return this; }), g;\r\n function verb(n) { return function (v) { return step([n, v]); }; }\r\n function step(op) {\r\n if (f) throw new TypeError(\"Generator is already executing.\");\r\n while (_) try {\r\n if (f = 1, y && (t = op[0] & 2 ? y[\"return\"] : op[0] ? y[\"throw\"] || ((t = y[\"return\"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;\r\n if (y = 0, t) op = [op[0] & 2, t.value];\r\n switch (op[0]) {\r\n case 0: case 1: t = op; break;\r\n case 4: _.label++; return { value: op[1], done: false };\r\n case 5: _.label++; y = op[1]; op = [0]; continue;\r\n case 7: op = _.ops.pop(); _.trys.pop(); continue;\r\n default:\r\n if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }\r\n if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }\r\n if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }\r\n if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }\r\n if (t[2]) _.ops.pop();\r\n _.trys.pop(); continue;\r\n }\r\n op = body.call(thisArg, _);\r\n } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }\r\n if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };\r\n }\r\n}\r\n\r\nexport var __createBinding = Object.create ? (function(o, m, k, k2) {\r\n if (k2 === undefined) k2 = k;\r\n Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });\r\n}) : (function(o, m, k, k2) {\r\n if (k2 === undefined) k2 = k;\r\n o[k2] = m[k];\r\n});\r\n\r\nexport function __exportStar(m, o) {\r\n for (var p in m) if (p !== \"default\" && !Object.prototype.hasOwnProperty.call(o, p)) __createBinding(o, m, p);\r\n}\r\n\r\nexport function __values(o) {\r\n var s = typeof Symbol === \"function\" && Symbol.iterator, m = s && o[s], i = 0;\r\n if (m) return m.call(o);\r\n if (o && typeof o.length === \"number\") return {\r\n next: function () {\r\n if (o && i >= o.length) o = void 0;\r\n return { value: o && o[i++], done: !o };\r\n }\r\n };\r\n throw new TypeError(s ? \"Object is not iterable.\" : \"Symbol.iterator is not defined.\");\r\n}\r\n\r\nexport function __read(o, n) {\r\n var m = typeof Symbol === \"function\" && o[Symbol.iterator];\r\n if (!m) return o;\r\n var i = m.call(o), r, ar = [], e;\r\n try {\r\n while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);\r\n }\r\n catch (error) { e = { error: error }; }\r\n finally {\r\n try {\r\n if (r && !r.done && (m = i[\"return\"])) m.call(i);\r\n }\r\n finally { if (e) throw e.error; }\r\n }\r\n return ar;\r\n}\r\n\r\n/** @deprecated */\r\nexport function __spread() {\r\n for (var ar = [], i = 0; i < arguments.length; i++)\r\n ar = ar.concat(__read(arguments[i]));\r\n return ar;\r\n}\r\n\r\n/** @deprecated */\r\nexport function __spreadArrays() {\r\n for (var s = 0, i = 0, il = arguments.length; i < il; i++) s += arguments[i].length;\r\n for (var r = Array(s), k = 0, i = 0; i < il; i++)\r\n for (var a = arguments[i], j = 0, jl = a.length; j < jl; j++, k++)\r\n r[k] = a[j];\r\n return r;\r\n}\r\n\r\nexport function __spreadArray(to, from, pack) {\r\n if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {\r\n if (ar || !(i in from)) {\r\n if (!ar) ar = Array.prototype.slice.call(from, 0, i);\r\n ar[i] = from[i];\r\n }\r\n }\r\n return to.concat(ar || Array.prototype.slice.call(from));\r\n}\r\n\r\nexport function __await(v) {\r\n return this instanceof __await ? (this.v = v, this) : new __await(v);\r\n}\r\n\r\nexport function __asyncGenerator(thisArg, _arguments, generator) {\r\n if (!Symbol.asyncIterator) throw new TypeError(\"Symbol.asyncIterator is not defined.\");\r\n var g = generator.apply(thisArg, _arguments || []), i, q = [];\r\n return i = {}, verb(\"next\"), verb(\"throw\"), verb(\"return\"), i[Symbol.asyncIterator] = function () { return this; }, i;\r\n function verb(n) { if (g[n]) i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; }\r\n function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }\r\n function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }\r\n function fulfill(value) { resume(\"next\", value); }\r\n function reject(value) { resume(\"throw\", value); }\r\n function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }\r\n}\r\n\r\nexport function __asyncDelegator(o) {\r\n var i, p;\r\n return i = {}, verb(\"next\"), verb(\"throw\", function (e) { throw e; }), verb(\"return\"), i[Symbol.iterator] = function () { return this; }, i;\r\n function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: n === \"return\" } : f ? f(v) : v; } : f; }\r\n}\r\n\r\nexport function __asyncValues(o) {\r\n if (!Symbol.asyncIterator) throw new TypeError(\"Symbol.asyncIterator is not defined.\");\r\n var m = o[Symbol.asyncIterator], i;\r\n return m ? m.call(o) : (o = typeof __values === \"function\" ? __values(o) : o[Symbol.iterator](), i = {}, verb(\"next\"), verb(\"throw\"), verb(\"return\"), i[Symbol.asyncIterator] = function () { return this; }, i);\r\n function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }\r\n function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }\r\n}\r\n\r\nexport function __makeTemplateObject(cooked, raw) {\r\n if (Object.defineProperty) { Object.defineProperty(cooked, \"raw\", { value: raw }); } else { cooked.raw = raw; }\r\n return cooked;\r\n};\r\n\r\nvar __setModuleDefault = Object.create ? (function(o, v) {\r\n Object.defineProperty(o, \"default\", { enumerable: true, value: v });\r\n}) : function(o, v) {\r\n o[\"default\"] = v;\r\n};\r\n\r\nexport function __importStar(mod) {\r\n if (mod && mod.__esModule) return mod;\r\n var result = {};\r\n if (mod != null) for (var k in mod) if (k !== \"default\" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);\r\n __setModuleDefault(result, mod);\r\n return result;\r\n}\r\n\r\nexport function __importDefault(mod) {\r\n return (mod && mod.__esModule) ? mod : { default: mod };\r\n}\r\n\r\nexport function __classPrivateFieldGet(receiver, state, kind, f) {\r\n if (kind === \"a\" && !f) throw new TypeError(\"Private accessor was defined without a getter\");\r\n if (typeof state === \"function\" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError(\"Cannot read private member from an object whose class did not declare it\");\r\n return kind === \"m\" ? f : kind === \"a\" ? f.call(receiver) : f ? f.value : state.get(receiver);\r\n}\r\n\r\nexport function __classPrivateFieldSet(receiver, state, value, kind, f) {\r\n if (kind === \"m\") throw new TypeError(\"Private method is not writable\");\r\n if (kind === \"a\" && !f) throw new TypeError(\"Private accessor was defined without a setter\");\r\n if (typeof state === \"function\" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError(\"Cannot write private member to an object whose class did not declare it\");\r\n return (kind === \"a\" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;\r\n}\r\n", "/**\n * Returns true if the object is a function.\n * @param value The value to check\n */\nexport function isFunction(value: any): value is (...args: any[]) => any {\n return typeof value === 'function';\n}\n", "/**\n * Used to create Error subclasses until the community moves away from ES5.\n *\n * This is because compiling from TypeScript down to ES5 has issues with subclassing Errors\n * as well as other built-in types: https://github.com/Microsoft/TypeScript/issues/12123\n *\n * @param createImpl A factory function to create the actual constructor implementation. The returned\n * function should be a named function that calls `_super` internally.\n */\nexport function createErrorClass(createImpl: (_super: any) => any): T {\n const _super = (instance: any) => {\n Error.call(instance);\n instance.stack = new Error().stack;\n };\n\n const ctorFunc = createImpl(_super);\n ctorFunc.prototype = Object.create(Error.prototype);\n ctorFunc.prototype.constructor = ctorFunc;\n return ctorFunc;\n}\n", "import { createErrorClass } from './createErrorClass';\n\nexport interface UnsubscriptionError extends Error {\n readonly errors: any[];\n}\n\nexport interface UnsubscriptionErrorCtor {\n /**\n * @deprecated Internal implementation detail. Do not construct error instances.\n * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269\n */\n new (errors: any[]): UnsubscriptionError;\n}\n\n/**\n * An error thrown when one or more errors have occurred during the\n * `unsubscribe` of a {@link Subscription}.\n */\nexport const UnsubscriptionError: UnsubscriptionErrorCtor = createErrorClass(\n (_super) =>\n function UnsubscriptionErrorImpl(this: any, errors: (Error | string)[]) {\n _super(this);\n this.message = errors\n ? `${errors.length} errors occurred during unsubscription:\n${errors.map((err, i) => `${i + 1}) ${err.toString()}`).join('\\n ')}`\n : '';\n this.name = 'UnsubscriptionError';\n this.errors = errors;\n }\n);\n", "/**\n * Removes an item from an array, mutating it.\n * @param arr The array to remove the item from\n * @param item The item to remove\n */\nexport function arrRemove(arr: T[] | undefined | null, item: T) {\n if (arr) {\n const index = arr.indexOf(item);\n 0 <= index && arr.splice(index, 1);\n }\n}\n", "import { isFunction } from './util/isFunction';\nimport { UnsubscriptionError } from './util/UnsubscriptionError';\nimport { SubscriptionLike, TeardownLogic, Unsubscribable } from './types';\nimport { arrRemove } from './util/arrRemove';\n\n/**\n * Represents a disposable resource, such as the execution of an Observable. A\n * Subscription has one important method, `unsubscribe`, that takes no argument\n * and just disposes the resource held by the subscription.\n *\n * Additionally, subscriptions may be grouped together through the `add()`\n * method, which will attach a child Subscription to the current Subscription.\n * When a Subscription is unsubscribed, all its children (and its grandchildren)\n * will be unsubscribed as well.\n *\n * @class Subscription\n */\nexport class Subscription implements SubscriptionLike {\n /** @nocollapse */\n public static EMPTY = (() => {\n const empty = new Subscription();\n empty.closed = true;\n return empty;\n })();\n\n /**\n * A flag to indicate whether this Subscription has already been unsubscribed.\n */\n public closed = false;\n\n private _parentage: Subscription[] | Subscription | null = null;\n\n /**\n * The list of registered finalizers to execute upon unsubscription. Adding and removing from this\n * list occurs in the {@link #add} and {@link #remove} methods.\n */\n private _finalizers: Exclude[] | null = null;\n\n /**\n * @param initialTeardown A function executed first as part of the finalization\n * process that is kicked off when {@link #unsubscribe} is called.\n */\n constructor(private initialTeardown?: () => void) {}\n\n /**\n * Disposes the resources held by the subscription. May, for instance, cancel\n * an ongoing Observable execution or cancel any other type of work that\n * started when the Subscription was created.\n * @return {void}\n */\n unsubscribe(): void {\n let errors: any[] | undefined;\n\n if (!this.closed) {\n this.closed = true;\n\n // Remove this from it's parents.\n const { _parentage } = this;\n if (_parentage) {\n this._parentage = null;\n if (Array.isArray(_parentage)) {\n for (const parent of _parentage) {\n parent.remove(this);\n }\n } else {\n _parentage.remove(this);\n }\n }\n\n const { initialTeardown: initialFinalizer } = this;\n if (isFunction(initialFinalizer)) {\n try {\n initialFinalizer();\n } catch (e) {\n errors = e instanceof UnsubscriptionError ? e.errors : [e];\n }\n }\n\n const { _finalizers } = this;\n if (_finalizers) {\n this._finalizers = null;\n for (const finalizer of _finalizers) {\n try {\n execFinalizer(finalizer);\n } catch (err) {\n errors = errors ?? [];\n if (err instanceof UnsubscriptionError) {\n errors = [...errors, ...err.errors];\n } else {\n errors.push(err);\n }\n }\n }\n }\n\n if (errors) {\n throw new UnsubscriptionError(errors);\n }\n }\n }\n\n /**\n * Adds a finalizer to this subscription, so that finalization will be unsubscribed/called\n * when this subscription is unsubscribed. If this subscription is already {@link #closed},\n * because it has already been unsubscribed, then whatever finalizer is passed to it\n * will automatically be executed (unless the finalizer itself is also a closed subscription).\n *\n * Closed Subscriptions cannot be added as finalizers to any subscription. Adding a closed\n * subscription to a any subscription will result in no operation. (A noop).\n *\n * Adding a subscription to itself, or adding `null` or `undefined` will not perform any\n * operation at all. (A noop).\n *\n * `Subscription` instances that are added to this instance will automatically remove themselves\n * if they are unsubscribed. Functions and {@link Unsubscribable} objects that you wish to remove\n * will need to be removed manually with {@link #remove}\n *\n * @param teardown The finalization logic to add to this subscription.\n */\n add(teardown: TeardownLogic): void {\n // Only add the finalizer if it's not undefined\n // and don't add a subscription to itself.\n if (teardown && teardown !== this) {\n if (this.closed) {\n // If this subscription is already closed,\n // execute whatever finalizer is handed to it automatically.\n execFinalizer(teardown);\n } else {\n if (teardown instanceof Subscription) {\n // We don't add closed subscriptions, and we don't add the same subscription\n // twice. Subscription unsubscribe is idempotent.\n if (teardown.closed || teardown._hasParent(this)) {\n return;\n }\n teardown._addParent(this);\n }\n (this._finalizers = this._finalizers ?? []).push(teardown);\n }\n }\n }\n\n /**\n * Checks to see if a this subscription already has a particular parent.\n * This will signal that this subscription has already been added to the parent in question.\n * @param parent the parent to check for\n */\n private _hasParent(parent: Subscription) {\n const { _parentage } = this;\n return _parentage === parent || (Array.isArray(_parentage) && _parentage.includes(parent));\n }\n\n /**\n * Adds a parent to this subscription so it can be removed from the parent if it\n * unsubscribes on it's own.\n *\n * NOTE: THIS ASSUMES THAT {@link _hasParent} HAS ALREADY BEEN CHECKED.\n * @param parent The parent subscription to add\n */\n private _addParent(parent: Subscription) {\n const { _parentage } = this;\n this._parentage = Array.isArray(_parentage) ? (_parentage.push(parent), _parentage) : _parentage ? [_parentage, parent] : parent;\n }\n\n /**\n * Called on a child when it is removed via {@link #remove}.\n * @param parent The parent to remove\n */\n private _removeParent(parent: Subscription) {\n const { _parentage } = this;\n if (_parentage === parent) {\n this._parentage = null;\n } else if (Array.isArray(_parentage)) {\n arrRemove(_parentage, parent);\n }\n }\n\n /**\n * Removes a finalizer from this subscription that was previously added with the {@link #add} method.\n *\n * Note that `Subscription` instances, when unsubscribed, will automatically remove themselves\n * from every other `Subscription` they have been added to. This means that using the `remove` method\n * is not a common thing and should be used thoughtfully.\n *\n * If you add the same finalizer instance of a function or an unsubscribable object to a `Subscription` instance\n * more than once, you will need to call `remove` the same number of times to remove all instances.\n *\n * All finalizer instances are removed to free up memory upon unsubscription.\n *\n * @param teardown The finalizer to remove from this subscription\n */\n remove(teardown: Exclude): void {\n const { _finalizers } = this;\n _finalizers && arrRemove(_finalizers, teardown);\n\n if (teardown instanceof Subscription) {\n teardown._removeParent(this);\n }\n }\n}\n\nexport const EMPTY_SUBSCRIPTION = Subscription.EMPTY;\n\nexport function isSubscription(value: any): value is Subscription {\n return (\n value instanceof Subscription ||\n (value && 'closed' in value && isFunction(value.remove) && isFunction(value.add) && isFunction(value.unsubscribe))\n );\n}\n\nfunction execFinalizer(finalizer: Unsubscribable | (() => void)) {\n if (isFunction(finalizer)) {\n finalizer();\n } else {\n finalizer.unsubscribe();\n }\n}\n", "import { Subscriber } from './Subscriber';\nimport { ObservableNotification } from './types';\n\n/**\n * The {@link GlobalConfig} object for RxJS. It is used to configure things\n * like how to react on unhandled errors.\n */\nexport const config: GlobalConfig = {\n onUnhandledError: null,\n onStoppedNotification: null,\n Promise: undefined,\n useDeprecatedSynchronousErrorHandling: false,\n useDeprecatedNextContext: false,\n};\n\n/**\n * The global configuration object for RxJS, used to configure things\n * like how to react on unhandled errors. Accessible via {@link config}\n * object.\n */\nexport interface GlobalConfig {\n /**\n * A registration point for unhandled errors from RxJS. These are errors that\n * cannot were not handled by consuming code in the usual subscription path. For\n * example, if you have this configured, and you subscribe to an observable without\n * providing an error handler, errors from that subscription will end up here. This\n * will _always_ be called asynchronously on another job in the runtime. This is because\n * we do not want errors thrown in this user-configured handler to interfere with the\n * behavior of the library.\n */\n onUnhandledError: ((err: any) => void) | null;\n\n /**\n * A registration point for notifications that cannot be sent to subscribers because they\n * have completed, errored or have been explicitly unsubscribed. By default, next, complete\n * and error notifications sent to stopped subscribers are noops. However, sometimes callers\n * might want a different behavior. For example, with sources that attempt to report errors\n * to stopped subscribers, a caller can configure RxJS to throw an unhandled error instead.\n * This will _always_ be called asynchronously on another job in the runtime. This is because\n * we do not want errors thrown in this user-configured handler to interfere with the\n * behavior of the library.\n */\n onStoppedNotification: ((notification: ObservableNotification, subscriber: Subscriber) => void) | null;\n\n /**\n * The promise constructor used by default for {@link Observable#toPromise toPromise} and {@link Observable#forEach forEach}\n * methods.\n *\n * @deprecated As of version 8, RxJS will no longer support this sort of injection of a\n * Promise constructor. If you need a Promise implementation other than native promises,\n * please polyfill/patch Promise as you see appropriate. Will be removed in v8.\n */\n Promise?: PromiseConstructorLike;\n\n /**\n * If true, turns on synchronous error rethrowing, which is a deprecated behavior\n * in v6 and higher. This behavior enables bad patterns like wrapping a subscribe\n * call in a try/catch block. It also enables producer interference, a nasty bug\n * where a multicast can be broken for all observers by a downstream consumer with\n * an unhandled error. DO NOT USE THIS FLAG UNLESS IT'S NEEDED TO BUY TIME\n * FOR MIGRATION REASONS.\n *\n * @deprecated As of version 8, RxJS will no longer support synchronous throwing\n * of unhandled errors. All errors will be thrown on a separate call stack to prevent bad\n * behaviors described above. Will be removed in v8.\n */\n useDeprecatedSynchronousErrorHandling: boolean;\n\n /**\n * If true, enables an as-of-yet undocumented feature from v5: The ability to access\n * `unsubscribe()` via `this` context in `next` functions created in observers passed\n * to `subscribe`.\n *\n * This is being removed because the performance was severely problematic, and it could also cause\n * issues when types other than POJOs are passed to subscribe as subscribers, as they will likely have\n * their `this` context overwritten.\n *\n * @deprecated As of version 8, RxJS will no longer support altering the\n * context of next functions provided as part of an observer to Subscribe. Instead,\n * you will have access to a subscription or a signal or token that will allow you to do things like\n * unsubscribe and test closed status. Will be removed in v8.\n */\n useDeprecatedNextContext: boolean;\n}\n", "import type { TimerHandle } from './timerHandle';\ntype SetTimeoutFunction = (handler: () => void, timeout?: number, ...args: any[]) => TimerHandle;\ntype ClearTimeoutFunction = (handle: TimerHandle) => void;\n\ninterface TimeoutProvider {\n setTimeout: SetTimeoutFunction;\n clearTimeout: ClearTimeoutFunction;\n delegate:\n | {\n setTimeout: SetTimeoutFunction;\n clearTimeout: ClearTimeoutFunction;\n }\n | undefined;\n}\n\nexport const timeoutProvider: TimeoutProvider = {\n // When accessing the delegate, use the variable rather than `this` so that\n // the functions can be called without being bound to the provider.\n setTimeout(handler: () => void, timeout?: number, ...args) {\n const { delegate } = timeoutProvider;\n if (delegate?.setTimeout) {\n return delegate.setTimeout(handler, timeout, ...args);\n }\n return setTimeout(handler, timeout, ...args);\n },\n clearTimeout(handle) {\n const { delegate } = timeoutProvider;\n return (delegate?.clearTimeout || clearTimeout)(handle as any);\n },\n delegate: undefined,\n};\n", "import { config } from '../config';\nimport { timeoutProvider } from '../scheduler/timeoutProvider';\n\n/**\n * Handles an error on another job either with the user-configured {@link onUnhandledError},\n * or by throwing it on that new job so it can be picked up by `window.onerror`, `process.on('error')`, etc.\n *\n * This should be called whenever there is an error that is out-of-band with the subscription\n * or when an error hits a terminal boundary of the subscription and no error handler was provided.\n *\n * @param err the error to report\n */\nexport function reportUnhandledError(err: any) {\n timeoutProvider.setTimeout(() => {\n const { onUnhandledError } = config;\n if (onUnhandledError) {\n // Execute the user-configured error handler.\n onUnhandledError(err);\n } else {\n // Throw so it is picked up by the runtime's uncaught error mechanism.\n throw err;\n }\n });\n}\n", "/* tslint:disable:no-empty */\nexport function noop() { }\n", "import { CompleteNotification, NextNotification, ErrorNotification } from './types';\n\n/**\n * A completion object optimized for memory use and created to be the\n * same \"shape\" as other notifications in v8.\n * @internal\n */\nexport const COMPLETE_NOTIFICATION = (() => createNotification('C', undefined, undefined) as CompleteNotification)();\n\n/**\n * Internal use only. Creates an optimized error notification that is the same \"shape\"\n * as other notifications.\n * @internal\n */\nexport function errorNotification(error: any): ErrorNotification {\n return createNotification('E', undefined, error) as any;\n}\n\n/**\n * Internal use only. Creates an optimized next notification that is the same \"shape\"\n * as other notifications.\n * @internal\n */\nexport function nextNotification(value: T) {\n return createNotification('N', value, undefined) as NextNotification;\n}\n\n/**\n * Ensures that all notifications created internally have the same \"shape\" in v8.\n *\n * TODO: This is only exported to support a crazy legacy test in `groupBy`.\n * @internal\n */\nexport function createNotification(kind: 'N' | 'E' | 'C', value: any, error: any) {\n return {\n kind,\n value,\n error,\n };\n}\n", "import { config } from '../config';\n\nlet context: { errorThrown: boolean; error: any } | null = null;\n\n/**\n * Handles dealing with errors for super-gross mode. Creates a context, in which\n * any synchronously thrown errors will be passed to {@link captureError}. Which\n * will record the error such that it will be rethrown after the call back is complete.\n * TODO: Remove in v8\n * @param cb An immediately executed function.\n */\nexport function errorContext(cb: () => void) {\n if (config.useDeprecatedSynchronousErrorHandling) {\n const isRoot = !context;\n if (isRoot) {\n context = { errorThrown: false, error: null };\n }\n cb();\n if (isRoot) {\n const { errorThrown, error } = context!;\n context = null;\n if (errorThrown) {\n throw error;\n }\n }\n } else {\n // This is the general non-deprecated path for everyone that\n // isn't crazy enough to use super-gross mode (useDeprecatedSynchronousErrorHandling)\n cb();\n }\n}\n\n/**\n * Captures errors only in super-gross mode.\n * @param err the error to capture\n */\nexport function captureError(err: any) {\n if (config.useDeprecatedSynchronousErrorHandling && context) {\n context.errorThrown = true;\n context.error = err;\n }\n}\n", "import { isFunction } from './util/isFunction';\nimport { Observer, ObservableNotification } from './types';\nimport { isSubscription, Subscription } from './Subscription';\nimport { config } from './config';\nimport { reportUnhandledError } from './util/reportUnhandledError';\nimport { noop } from './util/noop';\nimport { nextNotification, errorNotification, COMPLETE_NOTIFICATION } from './NotificationFactories';\nimport { timeoutProvider } from './scheduler/timeoutProvider';\nimport { captureError } from './util/errorContext';\n\n/**\n * Implements the {@link Observer} interface and extends the\n * {@link Subscription} class. While the {@link Observer} is the public API for\n * consuming the values of an {@link Observable}, all Observers get converted to\n * a Subscriber, in order to provide Subscription-like capabilities such as\n * `unsubscribe`. Subscriber is a common type in RxJS, and crucial for\n * implementing operators, but it is rarely used as a public API.\n *\n * @class Subscriber\n */\nexport class Subscriber extends Subscription implements Observer {\n /**\n * A static factory for a Subscriber, given a (potentially partial) definition\n * of an Observer.\n * @param next The `next` callback of an Observer.\n * @param error The `error` callback of an\n * Observer.\n * @param complete The `complete` callback of an\n * Observer.\n * @return A Subscriber wrapping the (partially defined)\n * Observer represented by the given arguments.\n * @nocollapse\n * @deprecated Do not use. Will be removed in v8. There is no replacement for this\n * method, and there is no reason to be creating instances of `Subscriber` directly.\n * If you have a specific use case, please file an issue.\n */\n static create(next?: (x?: T) => void, error?: (e?: any) => void, complete?: () => void): Subscriber {\n return new SafeSubscriber(next, error, complete);\n }\n\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n protected isStopped: boolean = false;\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n protected destination: Subscriber | Observer; // this `any` is the escape hatch to erase extra type param (e.g. R)\n\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n * There is no reason to directly create an instance of Subscriber. This type is exported for typings reasons.\n */\n constructor(destination?: Subscriber | Observer) {\n super();\n if (destination) {\n this.destination = destination;\n // Automatically chain subscriptions together here.\n // if destination is a Subscription, then it is a Subscriber.\n if (isSubscription(destination)) {\n destination.add(this);\n }\n } else {\n this.destination = EMPTY_OBSERVER;\n }\n }\n\n /**\n * The {@link Observer} callback to receive notifications of type `next` from\n * the Observable, with a value. The Observable may call this method 0 or more\n * times.\n * @param {T} [value] The `next` value.\n * @return {void}\n */\n next(value?: T): void {\n if (this.isStopped) {\n handleStoppedNotification(nextNotification(value), this);\n } else {\n this._next(value!);\n }\n }\n\n /**\n * The {@link Observer} callback to receive notifications of type `error` from\n * the Observable, with an attached `Error`. Notifies the Observer that\n * the Observable has experienced an error condition.\n * @param {any} [err] The `error` exception.\n * @return {void}\n */\n error(err?: any): void {\n if (this.isStopped) {\n handleStoppedNotification(errorNotification(err), this);\n } else {\n this.isStopped = true;\n this._error(err);\n }\n }\n\n /**\n * The {@link Observer} callback to receive a valueless notification of type\n * `complete` from the Observable. Notifies the Observer that the Observable\n * has finished sending push-based notifications.\n * @return {void}\n */\n complete(): void {\n if (this.isStopped) {\n handleStoppedNotification(COMPLETE_NOTIFICATION, this);\n } else {\n this.isStopped = true;\n this._complete();\n }\n }\n\n unsubscribe(): void {\n if (!this.closed) {\n this.isStopped = true;\n super.unsubscribe();\n this.destination = null!;\n }\n }\n\n protected _next(value: T): void {\n this.destination.next(value);\n }\n\n protected _error(err: any): void {\n try {\n this.destination.error(err);\n } finally {\n this.unsubscribe();\n }\n }\n\n protected _complete(): void {\n try {\n this.destination.complete();\n } finally {\n this.unsubscribe();\n }\n }\n}\n\n/**\n * This bind is captured here because we want to be able to have\n * compatibility with monoid libraries that tend to use a method named\n * `bind`. In particular, a library called Monio requires this.\n */\nconst _bind = Function.prototype.bind;\n\nfunction bind any>(fn: Fn, thisArg: any): Fn {\n return _bind.call(fn, thisArg);\n}\n\n/**\n * Internal optimization only, DO NOT EXPOSE.\n * @internal\n */\nclass ConsumerObserver implements Observer {\n constructor(private partialObserver: Partial>) {}\n\n next(value: T): void {\n const { partialObserver } = this;\n if (partialObserver.next) {\n try {\n partialObserver.next(value);\n } catch (error) {\n handleUnhandledError(error);\n }\n }\n }\n\n error(err: any): void {\n const { partialObserver } = this;\n if (partialObserver.error) {\n try {\n partialObserver.error(err);\n } catch (error) {\n handleUnhandledError(error);\n }\n } else {\n handleUnhandledError(err);\n }\n }\n\n complete(): void {\n const { partialObserver } = this;\n if (partialObserver.complete) {\n try {\n partialObserver.complete();\n } catch (error) {\n handleUnhandledError(error);\n }\n }\n }\n}\n\nexport class SafeSubscriber extends Subscriber {\n constructor(\n observerOrNext?: Partial> | ((value: T) => void) | null,\n error?: ((e?: any) => void) | null,\n complete?: (() => void) | null\n ) {\n super();\n\n let partialObserver: Partial>;\n if (isFunction(observerOrNext) || !observerOrNext) {\n // The first argument is a function, not an observer. The next\n // two arguments *could* be observers, or they could be empty.\n partialObserver = {\n next: (observerOrNext ?? undefined) as (((value: T) => void) | undefined),\n error: error ?? undefined,\n complete: complete ?? undefined,\n };\n } else {\n // The first argument is a partial observer.\n let context: any;\n if (this && config.useDeprecatedNextContext) {\n // This is a deprecated path that made `this.unsubscribe()` available in\n // next handler functions passed to subscribe. This only exists behind a flag\n // now, as it is *very* slow.\n context = Object.create(observerOrNext);\n context.unsubscribe = () => this.unsubscribe();\n partialObserver = {\n next: observerOrNext.next && bind(observerOrNext.next, context),\n error: observerOrNext.error && bind(observerOrNext.error, context),\n complete: observerOrNext.complete && bind(observerOrNext.complete, context),\n };\n } else {\n // The \"normal\" path. Just use the partial observer directly.\n partialObserver = observerOrNext;\n }\n }\n\n // Wrap the partial observer to ensure it's a full observer, and\n // make sure proper error handling is accounted for.\n this.destination = new ConsumerObserver(partialObserver);\n }\n}\n\nfunction handleUnhandledError(error: any) {\n if (config.useDeprecatedSynchronousErrorHandling) {\n captureError(error);\n } else {\n // Ideal path, we report this as an unhandled error,\n // which is thrown on a new call stack.\n reportUnhandledError(error);\n }\n}\n\n/**\n * An error handler used when no error handler was supplied\n * to the SafeSubscriber -- meaning no error handler was supplied\n * do the `subscribe` call on our observable.\n * @param err The error to handle\n */\nfunction defaultErrorHandler(err: any) {\n throw err;\n}\n\n/**\n * A handler for notifications that cannot be sent to a stopped subscriber.\n * @param notification The notification being sent\n * @param subscriber The stopped subscriber\n */\nfunction handleStoppedNotification(notification: ObservableNotification, subscriber: Subscriber) {\n const { onStoppedNotification } = config;\n onStoppedNotification && timeoutProvider.setTimeout(() => onStoppedNotification(notification, subscriber));\n}\n\n/**\n * The observer used as a stub for subscriptions where the user did not\n * pass any arguments to `subscribe`. Comes with the default error handling\n * behavior.\n */\nexport const EMPTY_OBSERVER: Readonly> & { closed: true } = {\n closed: true,\n next: noop,\n error: defaultErrorHandler,\n complete: noop,\n};\n", "/**\n * Symbol.observable or a string \"@@observable\". Used for interop\n *\n * @deprecated We will no longer be exporting this symbol in upcoming versions of RxJS.\n * Instead polyfill and use Symbol.observable directly *or* use https://www.npmjs.com/package/symbol-observable\n */\nexport const observable: string | symbol = (() => (typeof Symbol === 'function' && Symbol.observable) || '@@observable')();\n", "/**\n * This function takes one parameter and just returns it. Simply put,\n * this is like `(x: T): T => x`.\n *\n * ## Examples\n *\n * This is useful in some cases when using things like `mergeMap`\n *\n * ```ts\n * import { interval, take, map, range, mergeMap, identity } from 'rxjs';\n *\n * const source$ = interval(1000).pipe(take(5));\n *\n * const result$ = source$.pipe(\n * map(i => range(i)),\n * mergeMap(identity) // same as mergeMap(x => x)\n * );\n *\n * result$.subscribe({\n * next: console.log\n * });\n * ```\n *\n * Or when you want to selectively apply an operator\n *\n * ```ts\n * import { interval, take, identity } from 'rxjs';\n *\n * const shouldLimit = () => Math.random() < 0.5;\n *\n * const source$ = interval(1000);\n *\n * const result$ = source$.pipe(shouldLimit() ? take(5) : identity);\n *\n * result$.subscribe({\n * next: console.log\n * });\n * ```\n *\n * @param x Any value that is returned by this function\n * @returns The value passed as the first parameter to this function\n */\nexport function identity(x: T): T {\n return x;\n}\n", "import { identity } from './identity';\nimport { UnaryFunction } from '../types';\n\nexport function pipe(): typeof identity;\nexport function pipe(fn1: UnaryFunction): UnaryFunction;\nexport function pipe(fn1: UnaryFunction, fn2: UnaryFunction): UnaryFunction;\nexport function pipe(fn1: UnaryFunction, fn2: UnaryFunction, fn3: UnaryFunction): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction,\n fn9: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction,\n fn9: UnaryFunction,\n ...fns: UnaryFunction[]\n): UnaryFunction;\n\n/**\n * pipe() can be called on one or more functions, each of which can take one argument (\"UnaryFunction\")\n * and uses it to return a value.\n * It returns a function that takes one argument, passes it to the first UnaryFunction, and then\n * passes the result to the next one, passes that result to the next one, and so on. \n */\nexport function pipe(...fns: Array>): UnaryFunction {\n return pipeFromArray(fns);\n}\n\n/** @internal */\nexport function pipeFromArray(fns: Array>): UnaryFunction {\n if (fns.length === 0) {\n return identity as UnaryFunction;\n }\n\n if (fns.length === 1) {\n return fns[0];\n }\n\n return function piped(input: T): R {\n return fns.reduce((prev: any, fn: UnaryFunction) => fn(prev), input as any);\n };\n}\n", "import { Operator } from './Operator';\nimport { SafeSubscriber, Subscriber } from './Subscriber';\nimport { isSubscription, Subscription } from './Subscription';\nimport { TeardownLogic, OperatorFunction, Subscribable, Observer } from './types';\nimport { observable as Symbol_observable } from './symbol/observable';\nimport { pipeFromArray } from './util/pipe';\nimport { config } from './config';\nimport { isFunction } from './util/isFunction';\nimport { errorContext } from './util/errorContext';\n\n/**\n * A representation of any set of values over any amount of time. This is the most basic building block\n * of RxJS.\n *\n * @class Observable\n */\nexport class Observable implements Subscribable {\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n */\n source: Observable | undefined;\n\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n */\n operator: Operator | undefined;\n\n /**\n * @constructor\n * @param {Function} subscribe the function that is called when the Observable is\n * initially subscribed to. This function is given a Subscriber, to which new values\n * can be `next`ed, or an `error` method can be called to raise an error, or\n * `complete` can be called to notify of a successful completion.\n */\n constructor(subscribe?: (this: Observable, subscriber: Subscriber) => TeardownLogic) {\n if (subscribe) {\n this._subscribe = subscribe;\n }\n }\n\n // HACK: Since TypeScript inherits static properties too, we have to\n // fight against TypeScript here so Subject can have a different static create signature\n /**\n * Creates a new Observable by calling the Observable constructor\n * @owner Observable\n * @method create\n * @param {Function} subscribe? the subscriber function to be passed to the Observable constructor\n * @return {Observable} a new observable\n * @nocollapse\n * @deprecated Use `new Observable()` instead. Will be removed in v8.\n */\n static create: (...args: any[]) => any = (subscribe?: (subscriber: Subscriber) => TeardownLogic) => {\n return new Observable(subscribe);\n };\n\n /**\n * Creates a new Observable, with this Observable instance as the source, and the passed\n * operator defined as the new observable's operator.\n * @method lift\n * @param operator the operator defining the operation to take on the observable\n * @return a new observable with the Operator applied\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n * If you have implemented an operator using `lift`, it is recommended that you create an\n * operator by simply returning `new Observable()` directly. See \"Creating new operators from\n * scratch\" section here: https://rxjs.dev/guide/operators\n */\n lift(operator?: Operator): Observable {\n const observable = new Observable();\n observable.source = this;\n observable.operator = operator;\n return observable;\n }\n\n subscribe(observerOrNext?: Partial> | ((value: T) => void)): Subscription;\n /** @deprecated Instead of passing separate callback arguments, use an observer argument. Signatures taking separate callback arguments will be removed in v8. Details: https://rxjs.dev/deprecations/subscribe-arguments */\n subscribe(next?: ((value: T) => void) | null, error?: ((error: any) => void) | null, complete?: (() => void) | null): Subscription;\n /**\n * Invokes an execution of an Observable and registers Observer handlers for notifications it will emit.\n *\n * Use it when you have all these Observables, but still nothing is happening.\n *\n * `subscribe` is not a regular operator, but a method that calls Observable's internal `subscribe` function. It\n * might be for example a function that you passed to Observable's constructor, but most of the time it is\n * a library implementation, which defines what will be emitted by an Observable, and when it be will emitted. This means\n * that calling `subscribe` is actually the moment when Observable starts its work, not when it is created, as it is often\n * the thought.\n *\n * Apart from starting the execution of an Observable, this method allows you to listen for values\n * that an Observable emits, as well as for when it completes or errors. You can achieve this in two\n * of the following ways.\n *\n * The first way is creating an object that implements {@link Observer} interface. It should have methods\n * defined by that interface, but note that it should be just a regular JavaScript object, which you can create\n * yourself in any way you want (ES6 class, classic function constructor, object literal etc.). In particular, do\n * not attempt to use any RxJS implementation details to create Observers - you don't need them. Remember also\n * that your object does not have to implement all methods. If you find yourself creating a method that doesn't\n * do anything, you can simply omit it. Note however, if the `error` method is not provided and an error happens,\n * it will be thrown asynchronously. Errors thrown asynchronously cannot be caught using `try`/`catch`. Instead,\n * use the {@link onUnhandledError} configuration option or use a runtime handler (like `window.onerror` or\n * `process.on('error)`) to be notified of unhandled errors. Because of this, it's recommended that you provide\n * an `error` method to avoid missing thrown errors.\n *\n * The second way is to give up on Observer object altogether and simply provide callback functions in place of its methods.\n * This means you can provide three functions as arguments to `subscribe`, where the first function is equivalent\n * of a `next` method, the second of an `error` method and the third of a `complete` method. Just as in case of an Observer,\n * if you do not need to listen for something, you can omit a function by passing `undefined` or `null`,\n * since `subscribe` recognizes these functions by where they were placed in function call. When it comes\n * to the `error` function, as with an Observer, if not provided, errors emitted by an Observable will be thrown asynchronously.\n *\n * You can, however, subscribe with no parameters at all. This may be the case where you're not interested in terminal events\n * and you also handled emissions internally by using operators (e.g. using `tap`).\n *\n * Whichever style of calling `subscribe` you use, in both cases it returns a Subscription object.\n * This object allows you to call `unsubscribe` on it, which in turn will stop the work that an Observable does and will clean\n * up all resources that an Observable used. Note that cancelling a subscription will not call `complete` callback\n * provided to `subscribe` function, which is reserved for a regular completion signal that comes from an Observable.\n *\n * Remember that callbacks provided to `subscribe` are not guaranteed to be called asynchronously.\n * It is an Observable itself that decides when these functions will be called. For example {@link of}\n * by default emits all its values synchronously. Always check documentation for how given Observable\n * will behave when subscribed and if its default behavior can be modified with a `scheduler`.\n *\n * #### Examples\n *\n * Subscribe with an {@link guide/observer Observer}\n *\n * ```ts\n * import { of } from 'rxjs';\n *\n * const sumObserver = {\n * sum: 0,\n * next(value) {\n * console.log('Adding: ' + value);\n * this.sum = this.sum + value;\n * },\n * error() {\n * // We actually could just remove this method,\n * // since we do not really care about errors right now.\n * },\n * complete() {\n * console.log('Sum equals: ' + this.sum);\n * }\n * };\n *\n * of(1, 2, 3) // Synchronously emits 1, 2, 3 and then completes.\n * .subscribe(sumObserver);\n *\n * // Logs:\n * // 'Adding: 1'\n * // 'Adding: 2'\n * // 'Adding: 3'\n * // 'Sum equals: 6'\n * ```\n *\n * Subscribe with functions ({@link deprecations/subscribe-arguments deprecated})\n *\n * ```ts\n * import { of } from 'rxjs'\n *\n * let sum = 0;\n *\n * of(1, 2, 3).subscribe(\n * value => {\n * console.log('Adding: ' + value);\n * sum = sum + value;\n * },\n * undefined,\n * () => console.log('Sum equals: ' + sum)\n * );\n *\n * // Logs:\n * // 'Adding: 1'\n * // 'Adding: 2'\n * // 'Adding: 3'\n * // 'Sum equals: 6'\n * ```\n *\n * Cancel a subscription\n *\n * ```ts\n * import { interval } from 'rxjs';\n *\n * const subscription = interval(1000).subscribe({\n * next(num) {\n * console.log(num)\n * },\n * complete() {\n * // Will not be called, even when cancelling subscription.\n * console.log('completed!');\n * }\n * });\n *\n * setTimeout(() => {\n * subscription.unsubscribe();\n * console.log('unsubscribed!');\n * }, 2500);\n *\n * // Logs:\n * // 0 after 1s\n * // 1 after 2s\n * // 'unsubscribed!' after 2.5s\n * ```\n *\n * @param {Observer|Function} observerOrNext (optional) Either an observer with methods to be called,\n * or the first of three possible handlers, which is the handler for each value emitted from the subscribed\n * Observable.\n * @param {Function} error (optional) A handler for a terminal event resulting from an error. If no error handler is provided,\n * the error will be thrown asynchronously as unhandled.\n * @param {Function} complete (optional) A handler for a terminal event resulting from successful completion.\n * @return {Subscription} a subscription reference to the registered handlers\n * @method subscribe\n */\n subscribe(\n observerOrNext?: Partial> | ((value: T) => void) | null,\n error?: ((error: any) => void) | null,\n complete?: (() => void) | null\n ): Subscription {\n const subscriber = isSubscriber(observerOrNext) ? observerOrNext : new SafeSubscriber(observerOrNext, error, complete);\n\n errorContext(() => {\n const { operator, source } = this;\n subscriber.add(\n operator\n ? // We're dealing with a subscription in the\n // operator chain to one of our lifted operators.\n operator.call(subscriber, source)\n : source\n ? // If `source` has a value, but `operator` does not, something that\n // had intimate knowledge of our API, like our `Subject`, must have\n // set it. We're going to just call `_subscribe` directly.\n this._subscribe(subscriber)\n : // In all other cases, we're likely wrapping a user-provided initializer\n // function, so we need to catch errors and handle them appropriately.\n this._trySubscribe(subscriber)\n );\n });\n\n return subscriber;\n }\n\n /** @internal */\n protected _trySubscribe(sink: Subscriber): TeardownLogic {\n try {\n return this._subscribe(sink);\n } catch (err) {\n // We don't need to return anything in this case,\n // because it's just going to try to `add()` to a subscription\n // above.\n sink.error(err);\n }\n }\n\n /**\n * Used as a NON-CANCELLABLE means of subscribing to an observable, for use with\n * APIs that expect promises, like `async/await`. You cannot unsubscribe from this.\n *\n * **WARNING**: Only use this with observables you *know* will complete. If the source\n * observable does not complete, you will end up with a promise that is hung up, and\n * potentially all of the state of an async function hanging out in memory. To avoid\n * this situation, look into adding something like {@link timeout}, {@link take},\n * {@link takeWhile}, or {@link takeUntil} amongst others.\n *\n * #### Example\n *\n * ```ts\n * import { interval, take } from 'rxjs';\n *\n * const source$ = interval(1000).pipe(take(4));\n *\n * async function getTotal() {\n * let total = 0;\n *\n * await source$.forEach(value => {\n * total += value;\n * console.log('observable -> ' + value);\n * });\n *\n * return total;\n * }\n *\n * getTotal().then(\n * total => console.log('Total: ' + total)\n * );\n *\n * // Expected:\n * // 'observable -> 0'\n * // 'observable -> 1'\n * // 'observable -> 2'\n * // 'observable -> 3'\n * // 'Total: 6'\n * ```\n *\n * @param next a handler for each value emitted by the observable\n * @return a promise that either resolves on observable completion or\n * rejects with the handled error\n */\n forEach(next: (value: T) => void): Promise;\n\n /**\n * @param next a handler for each value emitted by the observable\n * @param promiseCtor a constructor function used to instantiate the Promise\n * @return a promise that either resolves on observable completion or\n * rejects with the handled error\n * @deprecated Passing a Promise constructor will no longer be available\n * in upcoming versions of RxJS. This is because it adds weight to the library, for very\n * little benefit. If you need this functionality, it is recommended that you either\n * polyfill Promise, or you create an adapter to convert the returned native promise\n * to whatever promise implementation you wanted. Will be removed in v8.\n */\n forEach(next: (value: T) => void, promiseCtor: PromiseConstructorLike): Promise;\n\n forEach(next: (value: T) => void, promiseCtor?: PromiseConstructorLike): Promise {\n promiseCtor = getPromiseCtor(promiseCtor);\n\n return new promiseCtor((resolve, reject) => {\n const subscriber = new SafeSubscriber({\n next: (value) => {\n try {\n next(value);\n } catch (err) {\n reject(err);\n subscriber.unsubscribe();\n }\n },\n error: reject,\n complete: resolve,\n });\n this.subscribe(subscriber);\n }) as Promise;\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): TeardownLogic {\n return this.source?.subscribe(subscriber);\n }\n\n /**\n * An interop point defined by the es7-observable spec https://github.com/zenparsing/es-observable\n * @method Symbol.observable\n * @return {Observable} this instance of the observable\n */\n [Symbol_observable]() {\n return this;\n }\n\n /* tslint:disable:max-line-length */\n pipe(): Observable;\n pipe(op1: OperatorFunction): Observable;\n pipe(op1: OperatorFunction, op2: OperatorFunction): Observable;\n pipe(op1: OperatorFunction, op2: OperatorFunction, op3: OperatorFunction): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction,\n op8: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction,\n op8: OperatorFunction,\n op9: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction,\n op8: OperatorFunction,\n op9: OperatorFunction,\n ...operations: OperatorFunction[]\n ): Observable;\n /* tslint:enable:max-line-length */\n\n /**\n * Used to stitch together functional operators into a chain.\n * @method pipe\n * @return {Observable} the Observable result of all of the operators having\n * been called in the order they were passed in.\n *\n * ## Example\n *\n * ```ts\n * import { interval, filter, map, scan } from 'rxjs';\n *\n * interval(1000)\n * .pipe(\n * filter(x => x % 2 === 0),\n * map(x => x + x),\n * scan((acc, x) => acc + x)\n * )\n * .subscribe(x => console.log(x));\n * ```\n */\n pipe(...operations: OperatorFunction[]): Observable {\n return pipeFromArray(operations)(this);\n }\n\n /* tslint:disable:max-line-length */\n /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */\n toPromise(): Promise;\n /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */\n toPromise(PromiseCtor: typeof Promise): Promise;\n /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */\n toPromise(PromiseCtor: PromiseConstructorLike): Promise;\n /* tslint:enable:max-line-length */\n\n /**\n * Subscribe to this Observable and get a Promise resolving on\n * `complete` with the last emission (if any).\n *\n * **WARNING**: Only use this with observables you *know* will complete. If the source\n * observable does not complete, you will end up with a promise that is hung up, and\n * potentially all of the state of an async function hanging out in memory. To avoid\n * this situation, look into adding something like {@link timeout}, {@link take},\n * {@link takeWhile}, or {@link takeUntil} amongst others.\n *\n * @method toPromise\n * @param [promiseCtor] a constructor function used to instantiate\n * the Promise\n * @return A Promise that resolves with the last value emit, or\n * rejects on an error. If there were no emissions, Promise\n * resolves with undefined.\n * @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise\n */\n toPromise(promiseCtor?: PromiseConstructorLike): Promise {\n promiseCtor = getPromiseCtor(promiseCtor);\n\n return new promiseCtor((resolve, reject) => {\n let value: T | undefined;\n this.subscribe(\n (x: T) => (value = x),\n (err: any) => reject(err),\n () => resolve(value)\n );\n }) as Promise;\n }\n}\n\n/**\n * Decides between a passed promise constructor from consuming code,\n * A default configured promise constructor, and the native promise\n * constructor and returns it. If nothing can be found, it will throw\n * an error.\n * @param promiseCtor The optional promise constructor to passed by consuming code\n */\nfunction getPromiseCtor(promiseCtor: PromiseConstructorLike | undefined) {\n return promiseCtor ?? config.Promise ?? Promise;\n}\n\nfunction isObserver(value: any): value is Observer {\n return value && isFunction(value.next) && isFunction(value.error) && isFunction(value.complete);\n}\n\nfunction isSubscriber(value: any): value is Subscriber {\n return (value && value instanceof Subscriber) || (isObserver(value) && isSubscription(value));\n}\n", "import { Observable } from '../Observable';\nimport { Subscriber } from '../Subscriber';\nimport { OperatorFunction } from '../types';\nimport { isFunction } from './isFunction';\n\n/**\n * Used to determine if an object is an Observable with a lift function.\n */\nexport function hasLift(source: any): source is { lift: InstanceType['lift'] } {\n return isFunction(source?.lift);\n}\n\n/**\n * Creates an `OperatorFunction`. Used to define operators throughout the library in a concise way.\n * @param init The logic to connect the liftedSource to the subscriber at the moment of subscription.\n */\nexport function operate(\n init: (liftedSource: Observable, subscriber: Subscriber) => (() => void) | void\n): OperatorFunction {\n return (source: Observable) => {\n if (hasLift(source)) {\n return source.lift(function (this: Subscriber, liftedSource: Observable) {\n try {\n return init(liftedSource, this);\n } catch (err) {\n this.error(err);\n }\n });\n }\n throw new TypeError('Unable to lift unknown Observable type');\n };\n}\n", "import { Subscriber } from '../Subscriber';\n\n/**\n * Creates an instance of an `OperatorSubscriber`.\n * @param destination The downstream subscriber.\n * @param onNext Handles next values, only called if this subscriber is not stopped or closed. Any\n * error that occurs in this function is caught and sent to the `error` method of this subscriber.\n * @param onError Handles errors from the subscription, any errors that occur in this handler are caught\n * and send to the `destination` error handler.\n * @param onComplete Handles completion notification from the subscription. Any errors that occur in\n * this handler are sent to the `destination` error handler.\n * @param onFinalize Additional teardown logic here. This will only be called on teardown if the\n * subscriber itself is not already closed. This is called after all other teardown logic is executed.\n */\nexport function createOperatorSubscriber(\n destination: Subscriber,\n onNext?: (value: T) => void,\n onComplete?: () => void,\n onError?: (err: any) => void,\n onFinalize?: () => void\n): Subscriber {\n return new OperatorSubscriber(destination, onNext, onComplete, onError, onFinalize);\n}\n\n/**\n * A generic helper for allowing operators to be created with a Subscriber and\n * use closures to capture necessary state from the operator function itself.\n */\nexport class OperatorSubscriber extends Subscriber {\n /**\n * Creates an instance of an `OperatorSubscriber`.\n * @param destination The downstream subscriber.\n * @param onNext Handles next values, only called if this subscriber is not stopped or closed. Any\n * error that occurs in this function is caught and sent to the `error` method of this subscriber.\n * @param onError Handles errors from the subscription, any errors that occur in this handler are caught\n * and send to the `destination` error handler.\n * @param onComplete Handles completion notification from the subscription. Any errors that occur in\n * this handler are sent to the `destination` error handler.\n * @param onFinalize Additional finalization logic here. This will only be called on finalization if the\n * subscriber itself is not already closed. This is called after all other finalization logic is executed.\n * @param shouldUnsubscribe An optional check to see if an unsubscribe call should truly unsubscribe.\n * NOTE: This currently **ONLY** exists to support the strange behavior of {@link groupBy}, where unsubscription\n * to the resulting observable does not actually disconnect from the source if there are active subscriptions\n * to any grouped observable. (DO NOT EXPOSE OR USE EXTERNALLY!!!)\n */\n constructor(\n destination: Subscriber,\n onNext?: (value: T) => void,\n onComplete?: () => void,\n onError?: (err: any) => void,\n private onFinalize?: () => void,\n private shouldUnsubscribe?: () => boolean\n ) {\n // It's important - for performance reasons - that all of this class's\n // members are initialized and that they are always initialized in the same\n // order. This will ensure that all OperatorSubscriber instances have the\n // same hidden class in V8. This, in turn, will help keep the number of\n // hidden classes involved in property accesses within the base class as\n // low as possible. If the number of hidden classes involved exceeds four,\n // the property accesses will become megamorphic and performance penalties\n // will be incurred - i.e. inline caches won't be used.\n //\n // The reasons for ensuring all instances have the same hidden class are\n // further discussed in this blog post from Benedikt Meurer:\n // https://benediktmeurer.de/2018/03/23/impact-of-polymorphism-on-component-based-frameworks-like-react/\n super(destination);\n this._next = onNext\n ? function (this: OperatorSubscriber, value: T) {\n try {\n onNext(value);\n } catch (err) {\n destination.error(err);\n }\n }\n : super._next;\n this._error = onError\n ? function (this: OperatorSubscriber, err: any) {\n try {\n onError(err);\n } catch (err) {\n // Send any errors that occur down stream.\n destination.error(err);\n } finally {\n // Ensure finalization.\n this.unsubscribe();\n }\n }\n : super._error;\n this._complete = onComplete\n ? function (this: OperatorSubscriber) {\n try {\n onComplete();\n } catch (err) {\n // Send any errors that occur down stream.\n destination.error(err);\n } finally {\n // Ensure finalization.\n this.unsubscribe();\n }\n }\n : super._complete;\n }\n\n unsubscribe() {\n if (!this.shouldUnsubscribe || this.shouldUnsubscribe()) {\n const { closed } = this;\n super.unsubscribe();\n // Execute additional teardown if we have any and we didn't already do so.\n !closed && this.onFinalize?.();\n }\n }\n}\n", "import { Subscription } from '../Subscription';\n\ninterface AnimationFrameProvider {\n schedule(callback: FrameRequestCallback): Subscription;\n requestAnimationFrame: typeof requestAnimationFrame;\n cancelAnimationFrame: typeof cancelAnimationFrame;\n delegate:\n | {\n requestAnimationFrame: typeof requestAnimationFrame;\n cancelAnimationFrame: typeof cancelAnimationFrame;\n }\n | undefined;\n}\n\nexport const animationFrameProvider: AnimationFrameProvider = {\n // When accessing the delegate, use the variable rather than `this` so that\n // the functions can be called without being bound to the provider.\n schedule(callback) {\n let request = requestAnimationFrame;\n let cancel: typeof cancelAnimationFrame | undefined = cancelAnimationFrame;\n const { delegate } = animationFrameProvider;\n if (delegate) {\n request = delegate.requestAnimationFrame;\n cancel = delegate.cancelAnimationFrame;\n }\n const handle = request((timestamp) => {\n // Clear the cancel function. The request has been fulfilled, so\n // attempting to cancel the request upon unsubscription would be\n // pointless.\n cancel = undefined;\n callback(timestamp);\n });\n return new Subscription(() => cancel?.(handle));\n },\n requestAnimationFrame(...args) {\n const { delegate } = animationFrameProvider;\n return (delegate?.requestAnimationFrame || requestAnimationFrame)(...args);\n },\n cancelAnimationFrame(...args) {\n const { delegate } = animationFrameProvider;\n return (delegate?.cancelAnimationFrame || cancelAnimationFrame)(...args);\n },\n delegate: undefined,\n};\n", "import { createErrorClass } from './createErrorClass';\n\nexport interface ObjectUnsubscribedError extends Error {}\n\nexport interface ObjectUnsubscribedErrorCtor {\n /**\n * @deprecated Internal implementation detail. Do not construct error instances.\n * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269\n */\n new (): ObjectUnsubscribedError;\n}\n\n/**\n * An error thrown when an action is invalid because the object has been\n * unsubscribed.\n *\n * @see {@link Subject}\n * @see {@link BehaviorSubject}\n *\n * @class ObjectUnsubscribedError\n */\nexport const ObjectUnsubscribedError: ObjectUnsubscribedErrorCtor = createErrorClass(\n (_super) =>\n function ObjectUnsubscribedErrorImpl(this: any) {\n _super(this);\n this.name = 'ObjectUnsubscribedError';\n this.message = 'object unsubscribed';\n }\n);\n", "import { Operator } from './Operator';\nimport { Observable } from './Observable';\nimport { Subscriber } from './Subscriber';\nimport { Subscription, EMPTY_SUBSCRIPTION } from './Subscription';\nimport { Observer, SubscriptionLike, TeardownLogic } from './types';\nimport { ObjectUnsubscribedError } from './util/ObjectUnsubscribedError';\nimport { arrRemove } from './util/arrRemove';\nimport { errorContext } from './util/errorContext';\n\n/**\n * A Subject is a special type of Observable that allows values to be\n * multicasted to many Observers. Subjects are like EventEmitters.\n *\n * Every Subject is an Observable and an Observer. You can subscribe to a\n * Subject, and you can call next to feed values as well as error and complete.\n */\nexport class Subject extends Observable implements SubscriptionLike {\n closed = false;\n\n private currentObservers: Observer[] | null = null;\n\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n observers: Observer[] = [];\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n isStopped = false;\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n hasError = false;\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n thrownError: any = null;\n\n /**\n * Creates a \"subject\" by basically gluing an observer to an observable.\n *\n * @nocollapse\n * @deprecated Recommended you do not use. Will be removed at some point in the future. Plans for replacement still under discussion.\n */\n static create: (...args: any[]) => any = (destination: Observer, source: Observable): AnonymousSubject => {\n return new AnonymousSubject(destination, source);\n };\n\n constructor() {\n // NOTE: This must be here to obscure Observable's constructor.\n super();\n }\n\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n lift(operator: Operator): Observable {\n const subject = new AnonymousSubject(this, this);\n subject.operator = operator as any;\n return subject as any;\n }\n\n /** @internal */\n protected _throwIfClosed() {\n if (this.closed) {\n throw new ObjectUnsubscribedError();\n }\n }\n\n next(value: T) {\n errorContext(() => {\n this._throwIfClosed();\n if (!this.isStopped) {\n if (!this.currentObservers) {\n this.currentObservers = Array.from(this.observers);\n }\n for (const observer of this.currentObservers) {\n observer.next(value);\n }\n }\n });\n }\n\n error(err: any) {\n errorContext(() => {\n this._throwIfClosed();\n if (!this.isStopped) {\n this.hasError = this.isStopped = true;\n this.thrownError = err;\n const { observers } = this;\n while (observers.length) {\n observers.shift()!.error(err);\n }\n }\n });\n }\n\n complete() {\n errorContext(() => {\n this._throwIfClosed();\n if (!this.isStopped) {\n this.isStopped = true;\n const { observers } = this;\n while (observers.length) {\n observers.shift()!.complete();\n }\n }\n });\n }\n\n unsubscribe() {\n this.isStopped = this.closed = true;\n this.observers = this.currentObservers = null!;\n }\n\n get observed() {\n return this.observers?.length > 0;\n }\n\n /** @internal */\n protected _trySubscribe(subscriber: Subscriber): TeardownLogic {\n this._throwIfClosed();\n return super._trySubscribe(subscriber);\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n this._throwIfClosed();\n this._checkFinalizedStatuses(subscriber);\n return this._innerSubscribe(subscriber);\n }\n\n /** @internal */\n protected _innerSubscribe(subscriber: Subscriber) {\n const { hasError, isStopped, observers } = this;\n if (hasError || isStopped) {\n return EMPTY_SUBSCRIPTION;\n }\n this.currentObservers = null;\n observers.push(subscriber);\n return new Subscription(() => {\n this.currentObservers = null;\n arrRemove(observers, subscriber);\n });\n }\n\n /** @internal */\n protected _checkFinalizedStatuses(subscriber: Subscriber) {\n const { hasError, thrownError, isStopped } = this;\n if (hasError) {\n subscriber.error(thrownError);\n } else if (isStopped) {\n subscriber.complete();\n }\n }\n\n /**\n * Creates a new Observable with this Subject as the source. You can do this\n * to create custom Observer-side logic of the Subject and conceal it from\n * code that uses the Observable.\n * @return {Observable} Observable that the Subject casts to\n */\n asObservable(): Observable {\n const observable: any = new Observable();\n observable.source = this;\n return observable;\n }\n}\n\n/**\n * @class AnonymousSubject\n */\nexport class AnonymousSubject extends Subject {\n constructor(\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n public destination?: Observer,\n source?: Observable\n ) {\n super();\n this.source = source;\n }\n\n next(value: T) {\n this.destination?.next?.(value);\n }\n\n error(err: any) {\n this.destination?.error?.(err);\n }\n\n complete() {\n this.destination?.complete?.();\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n return this.source?.subscribe(subscriber) ?? EMPTY_SUBSCRIPTION;\n }\n}\n", "import { Subject } from './Subject';\nimport { Subscriber } from './Subscriber';\nimport { Subscription } from './Subscription';\n\n/**\n * A variant of Subject that requires an initial value and emits its current\n * value whenever it is subscribed to.\n *\n * @class BehaviorSubject\n */\nexport class BehaviorSubject extends Subject {\n constructor(private _value: T) {\n super();\n }\n\n get value(): T {\n return this.getValue();\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n const subscription = super._subscribe(subscriber);\n !subscription.closed && subscriber.next(this._value);\n return subscription;\n }\n\n getValue(): T {\n const { hasError, thrownError, _value } = this;\n if (hasError) {\n throw thrownError;\n }\n this._throwIfClosed();\n return _value;\n }\n\n next(value: T): void {\n super.next((this._value = value));\n }\n}\n", "import { TimestampProvider } from '../types';\n\ninterface DateTimestampProvider extends TimestampProvider {\n delegate: TimestampProvider | undefined;\n}\n\nexport const dateTimestampProvider: DateTimestampProvider = {\n now() {\n // Use the variable rather than `this` so that the function can be called\n // without being bound to the provider.\n return (dateTimestampProvider.delegate || Date).now();\n },\n delegate: undefined,\n};\n", "import { Subject } from './Subject';\nimport { TimestampProvider } from './types';\nimport { Subscriber } from './Subscriber';\nimport { Subscription } from './Subscription';\nimport { dateTimestampProvider } from './scheduler/dateTimestampProvider';\n\n/**\n * A variant of {@link Subject} that \"replays\" old values to new subscribers by emitting them when they first subscribe.\n *\n * `ReplaySubject` has an internal buffer that will store a specified number of values that it has observed. Like `Subject`,\n * `ReplaySubject` \"observes\" values by having them passed to its `next` method. When it observes a value, it will store that\n * value for a time determined by the configuration of the `ReplaySubject`, as passed to its constructor.\n *\n * When a new subscriber subscribes to the `ReplaySubject` instance, it will synchronously emit all values in its buffer in\n * a First-In-First-Out (FIFO) manner. The `ReplaySubject` will also complete, if it has observed completion; and it will\n * error if it has observed an error.\n *\n * There are two main configuration items to be concerned with:\n *\n * 1. `bufferSize` - This will determine how many items are stored in the buffer, defaults to infinite.\n * 2. `windowTime` - The amount of time to hold a value in the buffer before removing it from the buffer.\n *\n * Both configurations may exist simultaneously. So if you would like to buffer a maximum of 3 values, as long as the values\n * are less than 2 seconds old, you could do so with a `new ReplaySubject(3, 2000)`.\n *\n * ### Differences with BehaviorSubject\n *\n * `BehaviorSubject` is similar to `new ReplaySubject(1)`, with a couple of exceptions:\n *\n * 1. `BehaviorSubject` comes \"primed\" with a single value upon construction.\n * 2. `ReplaySubject` will replay values, even after observing an error, where `BehaviorSubject` will not.\n *\n * @see {@link Subject}\n * @see {@link BehaviorSubject}\n * @see {@link shareReplay}\n */\nexport class ReplaySubject extends Subject {\n private _buffer: (T | number)[] = [];\n private _infiniteTimeWindow = true;\n\n /**\n * @param bufferSize The size of the buffer to replay on subscription\n * @param windowTime The amount of time the buffered items will stay buffered\n * @param timestampProvider An object with a `now()` method that provides the current timestamp. This is used to\n * calculate the amount of time something has been buffered.\n */\n constructor(\n private _bufferSize = Infinity,\n private _windowTime = Infinity,\n private _timestampProvider: TimestampProvider = dateTimestampProvider\n ) {\n super();\n this._infiniteTimeWindow = _windowTime === Infinity;\n this._bufferSize = Math.max(1, _bufferSize);\n this._windowTime = Math.max(1, _windowTime);\n }\n\n next(value: T): void {\n const { isStopped, _buffer, _infiniteTimeWindow, _timestampProvider, _windowTime } = this;\n if (!isStopped) {\n _buffer.push(value);\n !_infiniteTimeWindow && _buffer.push(_timestampProvider.now() + _windowTime);\n }\n this._trimBuffer();\n super.next(value);\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n this._throwIfClosed();\n this._trimBuffer();\n\n const subscription = this._innerSubscribe(subscriber);\n\n const { _infiniteTimeWindow, _buffer } = this;\n // We use a copy here, so reentrant code does not mutate our array while we're\n // emitting it to a new subscriber.\n const copy = _buffer.slice();\n for (let i = 0; i < copy.length && !subscriber.closed; i += _infiniteTimeWindow ? 1 : 2) {\n subscriber.next(copy[i] as T);\n }\n\n this._checkFinalizedStatuses(subscriber);\n\n return subscription;\n }\n\n private _trimBuffer() {\n const { _bufferSize, _timestampProvider, _buffer, _infiniteTimeWindow } = this;\n // If we don't have an infinite buffer size, and we're over the length,\n // use splice to truncate the old buffer values off. Note that we have to\n // double the size for instances where we're not using an infinite time window\n // because we're storing the values and the timestamps in the same array.\n const adjustedBufferSize = (_infiniteTimeWindow ? 1 : 2) * _bufferSize;\n _bufferSize < Infinity && adjustedBufferSize < _buffer.length && _buffer.splice(0, _buffer.length - adjustedBufferSize);\n\n // Now, if we're not in an infinite time window, remove all values where the time is\n // older than what is allowed.\n if (!_infiniteTimeWindow) {\n const now = _timestampProvider.now();\n let last = 0;\n // Search the array for the first timestamp that isn't expired and\n // truncate the buffer up to that point.\n for (let i = 1; i < _buffer.length && (_buffer[i] as number) <= now; i += 2) {\n last = i;\n }\n last && _buffer.splice(0, last + 1);\n }\n }\n}\n", "import { Scheduler } from '../Scheduler';\nimport { Subscription } from '../Subscription';\nimport { SchedulerAction } from '../types';\n\n/**\n * A unit of work to be executed in a `scheduler`. An action is typically\n * created from within a {@link SchedulerLike} and an RxJS user does not need to concern\n * themselves about creating and manipulating an Action.\n *\n * ```ts\n * class Action extends Subscription {\n * new (scheduler: Scheduler, work: (state?: T) => void);\n * schedule(state?: T, delay: number = 0): Subscription;\n * }\n * ```\n *\n * @class Action\n */\nexport class Action extends Subscription {\n constructor(scheduler: Scheduler, work: (this: SchedulerAction, state?: T) => void) {\n super();\n }\n /**\n * Schedules this action on its parent {@link SchedulerLike} for execution. May be passed\n * some context object, `state`. May happen at some point in the future,\n * according to the `delay` parameter, if specified.\n * @param {T} [state] Some contextual data that the `work` function uses when\n * called by the Scheduler.\n * @param {number} [delay] Time to wait before executing the work, where the\n * time unit is implicit and defined by the Scheduler.\n * @return {void}\n */\n public schedule(state?: T, delay: number = 0): Subscription {\n return this;\n }\n}\n", "import type { TimerHandle } from './timerHandle';\ntype SetIntervalFunction = (handler: () => void, timeout?: number, ...args: any[]) => TimerHandle;\ntype ClearIntervalFunction = (handle: TimerHandle) => void;\n\ninterface IntervalProvider {\n setInterval: SetIntervalFunction;\n clearInterval: ClearIntervalFunction;\n delegate:\n | {\n setInterval: SetIntervalFunction;\n clearInterval: ClearIntervalFunction;\n }\n | undefined;\n}\n\nexport const intervalProvider: IntervalProvider = {\n // When accessing the delegate, use the variable rather than `this` so that\n // the functions can be called without being bound to the provider.\n setInterval(handler: () => void, timeout?: number, ...args) {\n const { delegate } = intervalProvider;\n if (delegate?.setInterval) {\n return delegate.setInterval(handler, timeout, ...args);\n }\n return setInterval(handler, timeout, ...args);\n },\n clearInterval(handle) {\n const { delegate } = intervalProvider;\n return (delegate?.clearInterval || clearInterval)(handle as any);\n },\n delegate: undefined,\n};\n", "import { Action } from './Action';\nimport { SchedulerAction } from '../types';\nimport { Subscription } from '../Subscription';\nimport { AsyncScheduler } from './AsyncScheduler';\nimport { intervalProvider } from './intervalProvider';\nimport { arrRemove } from '../util/arrRemove';\nimport { TimerHandle } from './timerHandle';\n\nexport class AsyncAction extends Action {\n public id: TimerHandle | undefined;\n public state?: T;\n // @ts-ignore: Property has no initializer and is not definitely assigned\n public delay: number;\n protected pending: boolean = false;\n\n constructor(protected scheduler: AsyncScheduler, protected work: (this: SchedulerAction, state?: T) => void) {\n super(scheduler, work);\n }\n\n public schedule(state?: T, delay: number = 0): Subscription {\n if (this.closed) {\n return this;\n }\n\n // Always replace the current state with the new state.\n this.state = state;\n\n const id = this.id;\n const scheduler = this.scheduler;\n\n //\n // Important implementation note:\n //\n // Actions only execute once by default, unless rescheduled from within the\n // scheduled callback. This allows us to implement single and repeat\n // actions via the same code path, without adding API surface area, as well\n // as mimic traditional recursion but across asynchronous boundaries.\n //\n // However, JS runtimes and timers distinguish between intervals achieved by\n // serial `setTimeout` calls vs. a single `setInterval` call. An interval of\n // serial `setTimeout` calls can be individually delayed, which delays\n // scheduling the next `setTimeout`, and so on. `setInterval` attempts to\n // guarantee the interval callback will be invoked more precisely to the\n // interval period, regardless of load.\n //\n // Therefore, we use `setInterval` to schedule single and repeat actions.\n // If the action reschedules itself with the same delay, the interval is not\n // canceled. If the action doesn't reschedule, or reschedules with a\n // different delay, the interval will be canceled after scheduled callback\n // execution.\n //\n if (id != null) {\n this.id = this.recycleAsyncId(scheduler, id, delay);\n }\n\n // Set the pending flag indicating that this action has been scheduled, or\n // has recursively rescheduled itself.\n this.pending = true;\n\n this.delay = delay;\n // If this action has already an async Id, don't request a new one.\n this.id = this.id ?? this.requestAsyncId(scheduler, this.id, delay);\n\n return this;\n }\n\n protected requestAsyncId(scheduler: AsyncScheduler, _id?: TimerHandle, delay: number = 0): TimerHandle {\n return intervalProvider.setInterval(scheduler.flush.bind(scheduler, this), delay);\n }\n\n protected recycleAsyncId(_scheduler: AsyncScheduler, id?: TimerHandle, delay: number | null = 0): TimerHandle | undefined {\n // If this action is rescheduled with the same delay time, don't clear the interval id.\n if (delay != null && this.delay === delay && this.pending === false) {\n return id;\n }\n // Otherwise, if the action's delay time is different from the current delay,\n // or the action has been rescheduled before it's executed, clear the interval id\n if (id != null) {\n intervalProvider.clearInterval(id);\n }\n\n return undefined;\n }\n\n /**\n * Immediately executes this action and the `work` it contains.\n * @return {any}\n */\n public execute(state: T, delay: number): any {\n if (this.closed) {\n return new Error('executing a cancelled action');\n }\n\n this.pending = false;\n const error = this._execute(state, delay);\n if (error) {\n return error;\n } else if (this.pending === false && this.id != null) {\n // Dequeue if the action didn't reschedule itself. Don't call\n // unsubscribe(), because the action could reschedule later.\n // For example:\n // ```\n // scheduler.schedule(function doWork(counter) {\n // /* ... I'm a busy worker bee ... */\n // var originalAction = this;\n // /* wait 100ms before rescheduling the action */\n // setTimeout(function () {\n // originalAction.schedule(counter + 1);\n // }, 100);\n // }, 1000);\n // ```\n this.id = this.recycleAsyncId(this.scheduler, this.id, null);\n }\n }\n\n protected _execute(state: T, _delay: number): any {\n let errored: boolean = false;\n let errorValue: any;\n try {\n this.work(state);\n } catch (e) {\n errored = true;\n // HACK: Since code elsewhere is relying on the \"truthiness\" of the\n // return here, we can't have it return \"\" or 0 or false.\n // TODO: Clean this up when we refactor schedulers mid-version-8 or so.\n errorValue = e ? e : new Error('Scheduled action threw falsy error');\n }\n if (errored) {\n this.unsubscribe();\n return errorValue;\n }\n }\n\n unsubscribe() {\n if (!this.closed) {\n const { id, scheduler } = this;\n const { actions } = scheduler;\n\n this.work = this.state = this.scheduler = null!;\n this.pending = false;\n\n arrRemove(actions, this);\n if (id != null) {\n this.id = this.recycleAsyncId(scheduler, id, null);\n }\n\n this.delay = null!;\n super.unsubscribe();\n }\n }\n}\n", "import { Action } from './scheduler/Action';\nimport { Subscription } from './Subscription';\nimport { SchedulerLike, SchedulerAction } from './types';\nimport { dateTimestampProvider } from './scheduler/dateTimestampProvider';\n\n/**\n * An execution context and a data structure to order tasks and schedule their\n * execution. Provides a notion of (potentially virtual) time, through the\n * `now()` getter method.\n *\n * Each unit of work in a Scheduler is called an `Action`.\n *\n * ```ts\n * class Scheduler {\n * now(): number;\n * schedule(work, delay?, state?): Subscription;\n * }\n * ```\n *\n * @class Scheduler\n * @deprecated Scheduler is an internal implementation detail of RxJS, and\n * should not be used directly. Rather, create your own class and implement\n * {@link SchedulerLike}. Will be made internal in v8.\n */\nexport class Scheduler implements SchedulerLike {\n public static now: () => number = dateTimestampProvider.now;\n\n constructor(private schedulerActionCtor: typeof Action, now: () => number = Scheduler.now) {\n this.now = now;\n }\n\n /**\n * A getter method that returns a number representing the current time\n * (at the time this function was called) according to the scheduler's own\n * internal clock.\n * @return {number} A number that represents the current time. May or may not\n * have a relation to wall-clock time. May or may not refer to a time unit\n * (e.g. milliseconds).\n */\n public now: () => number;\n\n /**\n * Schedules a function, `work`, for execution. May happen at some point in\n * the future, according to the `delay` parameter, if specified. May be passed\n * some context object, `state`, which will be passed to the `work` function.\n *\n * The given arguments will be processed an stored as an Action object in a\n * queue of actions.\n *\n * @param {function(state: ?T): ?Subscription} work A function representing a\n * task, or some unit of work to be executed by the Scheduler.\n * @param {number} [delay] Time to wait before executing the work, where the\n * time unit is implicit and defined by the Scheduler itself.\n * @param {T} [state] Some contextual data that the `work` function uses when\n * called by the Scheduler.\n * @return {Subscription} A subscription in order to be able to unsubscribe\n * the scheduled work.\n */\n public schedule(work: (this: SchedulerAction, state?: T) => void, delay: number = 0, state?: T): Subscription {\n return new this.schedulerActionCtor(this, work).schedule(state, delay);\n }\n}\n", "import { Scheduler } from '../Scheduler';\nimport { Action } from './Action';\nimport { AsyncAction } from './AsyncAction';\nimport { TimerHandle } from './timerHandle';\n\nexport class AsyncScheduler extends Scheduler {\n public actions: Array> = [];\n /**\n * A flag to indicate whether the Scheduler is currently executing a batch of\n * queued actions.\n * @type {boolean}\n * @internal\n */\n public _active: boolean = false;\n /**\n * An internal ID used to track the latest asynchronous task such as those\n * coming from `setTimeout`, `setInterval`, `requestAnimationFrame`, and\n * others.\n * @type {any}\n * @internal\n */\n public _scheduled: TimerHandle | undefined;\n\n constructor(SchedulerAction: typeof Action, now: () => number = Scheduler.now) {\n super(SchedulerAction, now);\n }\n\n public flush(action: AsyncAction): void {\n const { actions } = this;\n\n if (this._active) {\n actions.push(action);\n return;\n }\n\n let error: any;\n this._active = true;\n\n do {\n if ((error = action.execute(action.state, action.delay))) {\n break;\n }\n } while ((action = actions.shift()!)); // exhaust the scheduler queue\n\n this._active = false;\n\n if (error) {\n while ((action = actions.shift()!)) {\n action.unsubscribe();\n }\n throw error;\n }\n }\n}\n", "import { AsyncAction } from './AsyncAction';\nimport { AsyncScheduler } from './AsyncScheduler';\n\n/**\n *\n * Async Scheduler\n *\n * Schedule task as if you used setTimeout(task, duration)\n *\n * `async` scheduler schedules tasks asynchronously, by putting them on the JavaScript\n * event loop queue. It is best used to delay tasks in time or to schedule tasks repeating\n * in intervals.\n *\n * If you just want to \"defer\" task, that is to perform it right after currently\n * executing synchronous code ends (commonly achieved by `setTimeout(deferredTask, 0)`),\n * better choice will be the {@link asapScheduler} scheduler.\n *\n * ## Examples\n * Use async scheduler to delay task\n * ```ts\n * import { asyncScheduler } from 'rxjs';\n *\n * const task = () => console.log('it works!');\n *\n * asyncScheduler.schedule(task, 2000);\n *\n * // After 2 seconds logs:\n * // \"it works!\"\n * ```\n *\n * Use async scheduler to repeat task in intervals\n * ```ts\n * import { asyncScheduler } from 'rxjs';\n *\n * function task(state) {\n * console.log(state);\n * this.schedule(state + 1, 1000); // `this` references currently executing Action,\n * // which we reschedule with new state and delay\n * }\n *\n * asyncScheduler.schedule(task, 3000, 0);\n *\n * // Logs:\n * // 0 after 3s\n * // 1 after 4s\n * // 2 after 5s\n * // 3 after 6s\n * ```\n */\n\nexport const asyncScheduler = new AsyncScheduler(AsyncAction);\n\n/**\n * @deprecated Renamed to {@link asyncScheduler}. Will be removed in v8.\n */\nexport const async = asyncScheduler;\n", "import { AsyncAction } from './AsyncAction';\nimport { Subscription } from '../Subscription';\nimport { QueueScheduler } from './QueueScheduler';\nimport { SchedulerAction } from '../types';\nimport { TimerHandle } from './timerHandle';\n\nexport class QueueAction extends AsyncAction {\n constructor(protected scheduler: QueueScheduler, protected work: (this: SchedulerAction, state?: T) => void) {\n super(scheduler, work);\n }\n\n public schedule(state?: T, delay: number = 0): Subscription {\n if (delay > 0) {\n return super.schedule(state, delay);\n }\n this.delay = delay;\n this.state = state;\n this.scheduler.flush(this);\n return this;\n }\n\n public execute(state: T, delay: number): any {\n return delay > 0 || this.closed ? super.execute(state, delay) : this._execute(state, delay);\n }\n\n protected requestAsyncId(scheduler: QueueScheduler, id?: TimerHandle, delay: number = 0): TimerHandle {\n // If delay exists and is greater than 0, or if the delay is null (the\n // action wasn't rescheduled) but was originally scheduled as an async\n // action, then recycle as an async action.\n\n if ((delay != null && delay > 0) || (delay == null && this.delay > 0)) {\n return super.requestAsyncId(scheduler, id, delay);\n }\n\n // Otherwise flush the scheduler starting with this action.\n scheduler.flush(this);\n\n // HACK: In the past, this was returning `void`. However, `void` isn't a valid\n // `TimerHandle`, and generally the return value here isn't really used. So the\n // compromise is to return `0` which is both \"falsy\" and a valid `TimerHandle`,\n // as opposed to refactoring every other instanceo of `requestAsyncId`.\n return 0;\n }\n}\n", "import { AsyncScheduler } from './AsyncScheduler';\n\nexport class QueueScheduler extends AsyncScheduler {\n}\n", "import { QueueAction } from './QueueAction';\nimport { QueueScheduler } from './QueueScheduler';\n\n/**\n *\n * Queue Scheduler\n *\n * Put every next task on a queue, instead of executing it immediately\n *\n * `queue` scheduler, when used with delay, behaves the same as {@link asyncScheduler} scheduler.\n *\n * When used without delay, it schedules given task synchronously - executes it right when\n * it is scheduled. However when called recursively, that is when inside the scheduled task,\n * another task is scheduled with queue scheduler, instead of executing immediately as well,\n * that task will be put on a queue and wait for current one to finish.\n *\n * This means that when you execute task with `queue` scheduler, you are sure it will end\n * before any other task scheduled with that scheduler will start.\n *\n * ## Examples\n * Schedule recursively first, then do something\n * ```ts\n * import { queueScheduler } from 'rxjs';\n *\n * queueScheduler.schedule(() => {\n * queueScheduler.schedule(() => console.log('second')); // will not happen now, but will be put on a queue\n *\n * console.log('first');\n * });\n *\n * // Logs:\n * // \"first\"\n * // \"second\"\n * ```\n *\n * Reschedule itself recursively\n * ```ts\n * import { queueScheduler } from 'rxjs';\n *\n * queueScheduler.schedule(function(state) {\n * if (state !== 0) {\n * console.log('before', state);\n * this.schedule(state - 1); // `this` references currently executing Action,\n * // which we reschedule with new state\n * console.log('after', state);\n * }\n * }, 0, 3);\n *\n * // In scheduler that runs recursively, you would expect:\n * // \"before\", 3\n * // \"before\", 2\n * // \"before\", 1\n * // \"after\", 1\n * // \"after\", 2\n * // \"after\", 3\n *\n * // But with queue it logs:\n * // \"before\", 3\n * // \"after\", 3\n * // \"before\", 2\n * // \"after\", 2\n * // \"before\", 1\n * // \"after\", 1\n * ```\n */\n\nexport const queueScheduler = new QueueScheduler(QueueAction);\n\n/**\n * @deprecated Renamed to {@link queueScheduler}. Will be removed in v8.\n */\nexport const queue = queueScheduler;\n", "import { AsyncAction } from './AsyncAction';\nimport { AnimationFrameScheduler } from './AnimationFrameScheduler';\nimport { SchedulerAction } from '../types';\nimport { animationFrameProvider } from './animationFrameProvider';\nimport { TimerHandle } from './timerHandle';\n\nexport class AnimationFrameAction extends AsyncAction {\n constructor(protected scheduler: AnimationFrameScheduler, protected work: (this: SchedulerAction, state?: T) => void) {\n super(scheduler, work);\n }\n\n protected requestAsyncId(scheduler: AnimationFrameScheduler, id?: TimerHandle, delay: number = 0): TimerHandle {\n // If delay is greater than 0, request as an async action.\n if (delay !== null && delay > 0) {\n return super.requestAsyncId(scheduler, id, delay);\n }\n // Push the action to the end of the scheduler queue.\n scheduler.actions.push(this);\n // If an animation frame has already been requested, don't request another\n // one. If an animation frame hasn't been requested yet, request one. Return\n // the current animation frame request id.\n return scheduler._scheduled || (scheduler._scheduled = animationFrameProvider.requestAnimationFrame(() => scheduler.flush(undefined)));\n }\n\n protected recycleAsyncId(scheduler: AnimationFrameScheduler, id?: TimerHandle, delay: number = 0): TimerHandle | undefined {\n // If delay exists and is greater than 0, or if the delay is null (the\n // action wasn't rescheduled) but was originally scheduled as an async\n // action, then recycle as an async action.\n if (delay != null ? delay > 0 : this.delay > 0) {\n return super.recycleAsyncId(scheduler, id, delay);\n }\n // If the scheduler queue has no remaining actions with the same async id,\n // cancel the requested animation frame and set the scheduled flag to\n // undefined so the next AnimationFrameAction will request its own.\n const { actions } = scheduler;\n if (id != null && actions[actions.length - 1]?.id !== id) {\n animationFrameProvider.cancelAnimationFrame(id as number);\n scheduler._scheduled = undefined;\n }\n // Return undefined so the action knows to request a new async id if it's rescheduled.\n return undefined;\n }\n}\n", "import { AsyncAction } from './AsyncAction';\nimport { AsyncScheduler } from './AsyncScheduler';\n\nexport class AnimationFrameScheduler extends AsyncScheduler {\n public flush(action?: AsyncAction): void {\n this._active = true;\n // The async id that effects a call to flush is stored in _scheduled.\n // Before executing an action, it's necessary to check the action's async\n // id to determine whether it's supposed to be executed in the current\n // flush.\n // Previous implementations of this method used a count to determine this,\n // but that was unsound, as actions that are unsubscribed - i.e. cancelled -\n // are removed from the actions array and that can shift actions that are\n // scheduled to be executed in a subsequent flush into positions at which\n // they are executed within the current flush.\n const flushId = this._scheduled;\n this._scheduled = undefined;\n\n const { actions } = this;\n let error: any;\n action = action || actions.shift()!;\n\n do {\n if ((error = action.execute(action.state, action.delay))) {\n break;\n }\n } while ((action = actions[0]) && action.id === flushId && actions.shift());\n\n this._active = false;\n\n if (error) {\n while ((action = actions[0]) && action.id === flushId && actions.shift()) {\n action.unsubscribe();\n }\n throw error;\n }\n }\n}\n", "import { AnimationFrameAction } from './AnimationFrameAction';\nimport { AnimationFrameScheduler } from './AnimationFrameScheduler';\n\n/**\n *\n * Animation Frame Scheduler\n *\n * Perform task when `window.requestAnimationFrame` would fire\n *\n * When `animationFrame` scheduler is used with delay, it will fall back to {@link asyncScheduler} scheduler\n * behaviour.\n *\n * Without delay, `animationFrame` scheduler can be used to create smooth browser animations.\n * It makes sure scheduled task will happen just before next browser content repaint,\n * thus performing animations as efficiently as possible.\n *\n * ## Example\n * Schedule div height animation\n * ```ts\n * // html:
\n * import { animationFrameScheduler } from 'rxjs';\n *\n * const div = document.querySelector('div');\n *\n * animationFrameScheduler.schedule(function(height) {\n * div.style.height = height + \"px\";\n *\n * this.schedule(height + 1); // `this` references currently executing Action,\n * // which we reschedule with new state\n * }, 0, 0);\n *\n * // You will see a div element growing in height\n * ```\n */\n\nexport const animationFrameScheduler = new AnimationFrameScheduler(AnimationFrameAction);\n\n/**\n * @deprecated Renamed to {@link animationFrameScheduler}. Will be removed in v8.\n */\nexport const animationFrame = animationFrameScheduler;\n", "import { Observable } from '../Observable';\nimport { SchedulerLike } from '../types';\n\n/**\n * A simple Observable that emits no items to the Observer and immediately\n * emits a complete notification.\n *\n * Just emits 'complete', and nothing else.\n *\n * ![](empty.png)\n *\n * A simple Observable that only emits the complete notification. It can be used\n * for composing with other Observables, such as in a {@link mergeMap}.\n *\n * ## Examples\n *\n * Log complete notification\n *\n * ```ts\n * import { EMPTY } from 'rxjs';\n *\n * EMPTY.subscribe({\n * next: () => console.log('Next'),\n * complete: () => console.log('Complete!')\n * });\n *\n * // Outputs\n * // Complete!\n * ```\n *\n * Emit the number 7, then complete\n *\n * ```ts\n * import { EMPTY, startWith } from 'rxjs';\n *\n * const result = EMPTY.pipe(startWith(7));\n * result.subscribe(x => console.log(x));\n *\n * // Outputs\n * // 7\n * ```\n *\n * Map and flatten only odd numbers to the sequence `'a'`, `'b'`, `'c'`\n *\n * ```ts\n * import { interval, mergeMap, of, EMPTY } from 'rxjs';\n *\n * const interval$ = interval(1000);\n * const result = interval$.pipe(\n * mergeMap(x => x % 2 === 1 ? of('a', 'b', 'c') : EMPTY),\n * );\n * result.subscribe(x => console.log(x));\n *\n * // Results in the following to the console:\n * // x is equal to the count on the interval, e.g. (0, 1, 2, 3, ...)\n * // x will occur every 1000ms\n * // if x % 2 is equal to 1, print a, b, c (each on its own)\n * // if x % 2 is not equal to 1, nothing will be output\n * ```\n *\n * @see {@link Observable}\n * @see {@link NEVER}\n * @see {@link of}\n * @see {@link throwError}\n */\nexport const EMPTY = new Observable((subscriber) => subscriber.complete());\n\n/**\n * @param scheduler A {@link SchedulerLike} to use for scheduling\n * the emission of the complete notification.\n * @deprecated Replaced with the {@link EMPTY} constant or {@link scheduled} (e.g. `scheduled([], scheduler)`). Will be removed in v8.\n */\nexport function empty(scheduler?: SchedulerLike) {\n return scheduler ? emptyScheduled(scheduler) : EMPTY;\n}\n\nfunction emptyScheduled(scheduler: SchedulerLike) {\n return new Observable((subscriber) => scheduler.schedule(() => subscriber.complete()));\n}\n", "import { SchedulerLike } from '../types';\nimport { isFunction } from './isFunction';\n\nexport function isScheduler(value: any): value is SchedulerLike {\n return value && isFunction(value.schedule);\n}\n", "import { SchedulerLike } from '../types';\nimport { isFunction } from './isFunction';\nimport { isScheduler } from './isScheduler';\n\nfunction last(arr: T[]): T | undefined {\n return arr[arr.length - 1];\n}\n\nexport function popResultSelector(args: any[]): ((...args: unknown[]) => unknown) | undefined {\n return isFunction(last(args)) ? args.pop() : undefined;\n}\n\nexport function popScheduler(args: any[]): SchedulerLike | undefined {\n return isScheduler(last(args)) ? args.pop() : undefined;\n}\n\nexport function popNumber(args: any[], defaultValue: number): number {\n return typeof last(args) === 'number' ? args.pop()! : defaultValue;\n}\n", "export const isArrayLike = ((x: any): x is ArrayLike => x && typeof x.length === 'number' && typeof x !== 'function');", "import { isFunction } from \"./isFunction\";\n\n/**\n * Tests to see if the object is \"thennable\".\n * @param value the object to test\n */\nexport function isPromise(value: any): value is PromiseLike {\n return isFunction(value?.then);\n}\n", "import { InteropObservable } from '../types';\nimport { observable as Symbol_observable } from '../symbol/observable';\nimport { isFunction } from './isFunction';\n\n/** Identifies an input as being Observable (but not necessary an Rx Observable) */\nexport function isInteropObservable(input: any): input is InteropObservable {\n return isFunction(input[Symbol_observable]);\n}\n", "import { isFunction } from './isFunction';\n\nexport function isAsyncIterable(obj: any): obj is AsyncIterable {\n return Symbol.asyncIterator && isFunction(obj?.[Symbol.asyncIterator]);\n}\n", "/**\n * Creates the TypeError to throw if an invalid object is passed to `from` or `scheduled`.\n * @param input The object that was passed.\n */\nexport function createInvalidObservableTypeError(input: any) {\n // TODO: We should create error codes that can be looked up, so this can be less verbose.\n return new TypeError(\n `You provided ${\n input !== null && typeof input === 'object' ? 'an invalid object' : `'${input}'`\n } where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.`\n );\n}\n", "export function getSymbolIterator(): symbol {\n if (typeof Symbol !== 'function' || !Symbol.iterator) {\n return '@@iterator' as any;\n }\n\n return Symbol.iterator;\n}\n\nexport const iterator = getSymbolIterator();\n", "import { iterator as Symbol_iterator } from '../symbol/iterator';\nimport { isFunction } from './isFunction';\n\n/** Identifies an input as being an Iterable */\nexport function isIterable(input: any): input is Iterable {\n return isFunction(input?.[Symbol_iterator]);\n}\n", "import { ReadableStreamLike } from '../types';\nimport { isFunction } from './isFunction';\n\nexport async function* readableStreamLikeToAsyncGenerator(readableStream: ReadableStreamLike): AsyncGenerator {\n const reader = readableStream.getReader();\n try {\n while (true) {\n const { value, done } = await reader.read();\n if (done) {\n return;\n }\n yield value!;\n }\n } finally {\n reader.releaseLock();\n }\n}\n\nexport function isReadableStreamLike(obj: any): obj is ReadableStreamLike {\n // We don't want to use instanceof checks because they would return\n // false for instances from another Realm, like an +

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.

+ + + +

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

+
ff start dev
+this will take a few seconds longer since this is the first time you're running this stack...
+done
+
+Web UI for member '0': http://127.0.0.1:5000/ui
+Sandbox UI for member '0': http://127.0.0.1:5109
+
+Web UI for member '1': http://127.0.0.1:5001/ui
+Sandbox UI for member '1': http://127.0.0.1:5209
+
+Web UI for member '2': http://127.0.0.1:5002/ui
+Sandbox UI for member '2': http://127.0.0.1:5309
+
+
+To see logs for your stack run:
+
+ff logs dev
+
+

Sandbox Layout

+

Sandbox Messages

+

The Sandbox is split up into three columns:

+

Left column: Prepare your request

+

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.

+

The first tab we will explore is the MESSAGING tab. This is where we can send broadcasts and private messages.

+

Middle column: Preview server code and see response

+

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 RUN button to actually send the request.

+

Right column: Events received on the WebSocket

+

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.

+

Messages

+

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.

+

Things to try out

+
    +
  • Send a broadcast message and view the data payload in every member's FireFly Explorer
    • +
  • Send a private message to one member, and verify that the data payload is not visible in the third member's FireFly Explorer
    • +
  • Send an image file and download it from another member's FireFly Explorer
    • +
+

Sandbox Messages

+

Tokens

+

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.

+

Things to try out

+
    +
  • Create a fungible token pool and mint some tokens and view your balance in the FireFly Explorer
    • +
  • Transfer some amount of those tokens to another member and view the transfer transaction in the FireFly Explorer
    • +
  • Burn some amount of tokens and view the transaction and updated balances in the FireFly Explorer
    • +
  • Create a non-fungible token pool and mint some NFTs
    • +
  • Transfer an NFT to another member and verify the account balances in the FireFly Explorer
    • +
+

Sandbox Tokens

+

Contracts

+

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.

+

Sandbox Tokens

+

Sandbox Tokens

+

Things to try out

+
    +
  • Create a contract interface and API, then view the Swagger UI for your new API
    • +
  • Create an event listener
    • +
  • 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.
    • +
+

Go forth and build!

+

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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/gettingstarted/setup_env/index.html b/v1.3.1/gettingstarted/setup_env/index.html new file mode 100644 index 000000000..38b055a66 --- /dev/null +++ b/v1.3.1/gettingstarted/setup_env/index.html @@ -0,0 +1,3681 @@ + + + + + + + + + + + + + + + + + + + + + + + ② Start your environment - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Start your environment

+

Previous steps: Install the FireFly CLI

+

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.

+

← ① Install the FireFly CLI

+

Now that you have the FireFly CLI installed, you are ready to run some Supernodes on your machine!

+

A FireFly Stack

+

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.

+

FireFly Stack

+

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.

+

System Resources

+

The FireFly stack will run in a docker-compose 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.

+

Docker Resources

+

Creating a new stack

+

It's really easy to create a new FireFly stack. The ff init 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.

+

To create an Ethereum based stack, run:

+
ff init ethereum
+
+

To create an Fabric based stack, run:

+
ff init fabric
+
+

Choose a stack name. For this guide, I will choose the name dev, but you can pick whatever you want:

+
stack name: dev
+
+

Chose the number of members for your stack. For this guide, we should pick 3 members, so we can try out both public and private messaging use cases:

+
number of members: 3
+
+

ff start

+

Stack initialization options

+

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 ff init ethereum --help or to see the full list of Fabric options run ff init fabric --help

+
ff init ethereum --help
+Create a new FireFly local dev stack using an Ethereum blockchain
+
+Usage:
+  ff init ethereum [stack_name] [member_count] [flags]
+
+Flags:
+      --block-period int              Block period in seconds. Default is variable based on selected blockchain provider. (default -1)
+  -c, --blockchain-connector string   Blockchain connector to use. Options are: [evmconnect ethconnect] (default "evmconnect")
+  -n, --blockchain-node string        Blockchain node type to use. Options are: [geth besu remote-rpc] (default "geth")
+      --chain-id int                  The chain ID - also used as the network ID (default 2021)
+      --contract-address string       Do not automatically deploy a contract, instead use a pre-configured address
+  -h, --help                          help for ethereum
+      --remote-node-url string        For cases where the node is pre-existing and running remotely
+
+Global Flags:
+      --ansi string                   control when to print ANSI control characters ("never"|"always"|"auto") (default "auto")
+      --channel string                Select the FireFly release channel to use. Options are: [stable head alpha beta rc] (default "stable")
+      --connector-config string       The path to a yaml file containing extra config for the blockchain connector
+      --core-config string            The path to a yaml file containing extra config for FireFly Core
+  -d, --database string               Database type to use. Options are: [sqlite3 postgres] (default "sqlite3")
+  -e, --external int                  Manage a number of FireFly core processes outside of the docker-compose stack - useful for development and debugging
+  -p, --firefly-base-port int         Mapped port base of FireFly core API (1 added for each member) (default 5000)
+      --ipfs-mode string              Set the mode in which IFPS operates. Options are: [private public] (default "private")
+  -m, --manifest string               Path to a manifest.json file containing the versions of each FireFly microservice to use. Overrides the --release flag.
+      --multiparty                    Enable or disable multiparty mode (default true)
+      --node-name stringArray         Node name
+      --org-name stringArray          Organization name
+      --prometheus-enabled            Enables Prometheus metrics exposition and aggregation to a shared Prometheus server
+      --prometheus-port int           Port for the shared Prometheus server (default 9090)
+      --prompt-names                  Prompt for org and node names instead of using the defaults
+  -r, --release string                Select the FireFly release version to use. Options are: [stable head alpha beta rc] (default "latest")
+      --request-timeout int           Custom request timeout (in seconds) - useful for registration to public chains
+      --sandbox-enabled               Enables the FireFly Sandbox to be started with your FireFly stack (default true)
+  -s, --services-base-port int        Mapped port base of services (100 added for each member) (default 5100)
+  -t, --token-providers stringArray   Token providers to use. Options are: [none erc1155 erc20_erc721] (default [erc20_erc721])
+  -v, --verbose                       verbose log output
+
+

Start your stack

+

To start your stack simply run:

+
ff start dev
+
+

This may take a minute or two and in the background the FireFly CLI will do the following for you:

+
    +
  • Download Docker images for all of the components of the Supernode
    • +
  • Initialize a new blockchain and blockchain node running inside a container
    • +
  • Set up configuration between all the components
    • +
  • Deploy FireFly's BatchPin smart contract
    • +
  • Deploy an ERC-1155 token smart contract
    • +
  • Register an identity for each member and node
    • +
+
+

NOTE: For macOS users, the default port (5000) is already in-use by ControlCe service (AirPlay Receiver). You can either disable this service in your environment, or use a different port when creating your stack (e.g. ff init dev -p 8000)

+
+

After your stack finishes starting it will print out the links to each member's UI and the Sandbox for that node:

+
ff start dev
+this will take a few seconds longer since this is the first time you're running this stack...
+done
+
+Web UI for member '0': http://127.0.0.1:5000/ui
+Sandbox UI for member '0': http://127.0.0.1:5109
+
+Web UI for member '1': http://127.0.0.1:5001/ui
+Sandbox UI for member '1': http://127.0.0.1:5209
+
+Web UI for member '2': http://127.0.0.1:5002/ui
+Sandbox UI for member '2': http://127.0.0.1:5309
+
+
+To see logs for your stack run:
+
+ff logs dev
+
+

Next steps: Use in the Sandbox

+

Now that you have some Supernodes running, it's time to start playing: in the Sandbox!

+

③ Use the Sandbox →

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/images/account_address.png b/v1.3.1/images/account_address.png new file mode 100644 index 000000000..6837b6742 Binary files /dev/null and b/v1.3.1/images/account_address.png differ diff --git a/v1.3.1/images/actions.png b/v1.3.1/images/actions.png new file mode 100644 index 000000000..cd1ce74f9 Binary files /dev/null and b/v1.3.1/images/actions.png differ diff --git a/v1.3.1/images/add_network.png b/v1.3.1/images/add_network.png new file mode 100644 index 000000000..b6db864ee Binary files /dev/null and b/v1.3.1/images/add_network.png differ diff --git a/v1.3.1/images/asset_transfer_swagger.png b/v1.3.1/images/asset_transfer_swagger.png new file mode 100644 index 000000000..14dcc4ccc Binary files /dev/null and b/v1.3.1/images/asset_transfer_swagger.png differ diff --git a/v1.3.1/images/blockchain-sub-status.png b/v1.3.1/images/blockchain-sub-status.png new file mode 100644 index 000000000..b5c8cee1b Binary files /dev/null and b/v1.3.1/images/blockchain-sub-status.png differ diff --git a/v1.3.1/images/contract_address.png b/v1.3.1/images/contract_address.png new file mode 100644 index 000000000..ec8852c38 Binary files /dev/null and b/v1.3.1/images/contract_address.png differ diff --git a/v1.3.1/images/create_release.png b/v1.3.1/images/create_release.png new file mode 100644 index 000000000..981049951 Binary files /dev/null and b/v1.3.1/images/create_release.png differ diff --git a/v1.3.1/images/define_a_datatype.png b/v1.3.1/images/define_a_datatype.png new file mode 100644 index 000000000..f66614651 Binary files /dev/null and b/v1.3.1/images/define_a_datatype.png differ diff --git a/v1.3.1/images/docker_memory.png b/v1.3.1/images/docker_memory.png new file mode 100644 index 000000000..19e74292f Binary files /dev/null and b/v1.3.1/images/docker_memory.png differ diff --git a/v1.3.1/images/draft_release.png b/v1.3.1/images/draft_release.png new file mode 100644 index 000000000..688b41a02 Binary files /dev/null and b/v1.3.1/images/draft_release.png differ diff --git a/v1.3.1/images/event_driven_programming_model.jpg b/v1.3.1/images/event_driven_programming_model.jpg new file mode 100644 index 000000000..eda8ac5c6 Binary files /dev/null and b/v1.3.1/images/event_driven_programming_model.jpg differ diff --git a/v1.3.1/images/ff_start.gif b/v1.3.1/images/ff_start.gif new file mode 100644 index 000000000..47a23c055 Binary files /dev/null and b/v1.3.1/images/ff_start.gif differ diff --git a/v1.3.1/images/firefly-getting-started-steps.png b/v1.3.1/images/firefly-getting-started-steps.png new file mode 100644 index 000000000..20c6a67fa Binary files /dev/null and b/v1.3.1/images/firefly-getting-started-steps.png differ diff --git a/v1.3.1/images/firefly_architecture_overview.jpg b/v1.3.1/images/firefly_architecture_overview.jpg new file mode 100644 index 000000000..7e211d58e Binary files /dev/null and b/v1.3.1/images/firefly_architecture_overview.jpg differ diff --git a/v1.3.1/images/firefly_blockchain_connector_framework.png b/v1.3.1/images/firefly_blockchain_connector_framework.png new file mode 100644 index 000000000..c4c504ea2 Binary files /dev/null and b/v1.3.1/images/firefly_blockchain_connector_framework.png differ diff --git a/v1.3.1/images/firefly_cli.png b/v1.3.1/images/firefly_cli.png new file mode 100644 index 000000000..ba2659989 Binary files /dev/null and b/v1.3.1/images/firefly_cli.png differ diff --git a/v1.3.1/images/firefly_connector_toolkit_event_streams.jpg b/v1.3.1/images/firefly_connector_toolkit_event_streams.jpg new file mode 100644 index 000000000..0bd5ac569 Binary files /dev/null and b/v1.3.1/images/firefly_connector_toolkit_event_streams.jpg differ diff --git a/v1.3.1/images/firefly_core.png b/v1.3.1/images/firefly_core.png new file mode 100644 index 000000000..e39c114f6 Binary files /dev/null and b/v1.3.1/images/firefly_core.png differ diff --git a/v1.3.1/images/firefly_data_privacy_model.jpg b/v1.3.1/images/firefly_data_privacy_model.jpg new file mode 100644 index 000000000..750bd471b Binary files /dev/null and b/v1.3.1/images/firefly_data_privacy_model.jpg differ diff --git a/v1.3.1/images/firefly_data_transport_layers.png b/v1.3.1/images/firefly_data_transport_layers.png new file mode 100644 index 000000000..6a46c7e7e Binary files /dev/null and b/v1.3.1/images/firefly_data_transport_layers.png differ diff --git a/v1.3.1/images/firefly_event_bus.jpg b/v1.3.1/images/firefly_event_bus.jpg new file mode 100644 index 000000000..73b935797 Binary files /dev/null and b/v1.3.1/images/firefly_event_bus.jpg differ diff --git a/v1.3.1/images/firefly_event_model.jpg b/v1.3.1/images/firefly_event_model.jpg new file mode 100644 index 000000000..90bc4d797 Binary files /dev/null and b/v1.3.1/images/firefly_event_model.jpg differ diff --git a/v1.3.1/images/firefly_event_subscription_model.jpg b/v1.3.1/images/firefly_event_subscription_model.jpg new file mode 100644 index 000000000..563e042fb Binary files /dev/null and b/v1.3.1/images/firefly_event_subscription_model.jpg differ diff --git a/v1.3.1/images/firefly_explorer.png b/v1.3.1/images/firefly_explorer.png new file mode 100644 index 000000000..9b1975a05 Binary files /dev/null and b/v1.3.1/images/firefly_explorer.png differ diff --git a/v1.3.1/images/firefly_first_successful_transaction.png b/v1.3.1/images/firefly_first_successful_transaction.png new file mode 100644 index 000000000..4d5946455 Binary files /dev/null and b/v1.3.1/images/firefly_first_successful_transaction.png differ diff --git a/v1.3.1/images/firefly_functionality_overview.png b/v1.3.1/images/firefly_functionality_overview.png new file mode 100644 index 000000000..b29c88319 Binary files /dev/null and b/v1.3.1/images/firefly_functionality_overview.png differ diff --git a/v1.3.1/images/firefly_functionality_overview_apps.png b/v1.3.1/images/firefly_functionality_overview_apps.png new file mode 100644 index 000000000..140ba4f91 Binary files /dev/null and b/v1.3.1/images/firefly_functionality_overview_apps.png differ diff --git a/v1.3.1/images/firefly_functionality_overview_connectivity.png b/v1.3.1/images/firefly_functionality_overview_connectivity.png new file mode 100644 index 000000000..aab49eb7c Binary files /dev/null and b/v1.3.1/images/firefly_functionality_overview_connectivity.png differ diff --git a/v1.3.1/images/firefly_functionality_overview_digital_assets.png b/v1.3.1/images/firefly_functionality_overview_digital_assets.png new file mode 100644 index 000000000..5946101ca Binary files /dev/null and b/v1.3.1/images/firefly_functionality_overview_digital_assets.png differ diff --git a/v1.3.1/images/firefly_functionality_overview_flows.png b/v1.3.1/images/firefly_functionality_overview_flows.png new file mode 100644 index 000000000..d01699214 Binary files /dev/null and b/v1.3.1/images/firefly_functionality_overview_flows.png differ diff --git a/v1.3.1/images/firefly_functionality_overview_orchestration_engine.png b/v1.3.1/images/firefly_functionality_overview_orchestration_engine.png new file mode 100644 index 000000000..30ca31928 Binary files /dev/null and b/v1.3.1/images/firefly_functionality_overview_orchestration_engine.png differ diff --git a/v1.3.1/images/firefly_functionality_overview_security.png b/v1.3.1/images/firefly_functionality_overview_security.png new file mode 100644 index 000000000..352e196d3 Binary files /dev/null and b/v1.3.1/images/firefly_functionality_overview_security.png differ diff --git a/v1.3.1/images/firefly_functionality_overview_tools.png b/v1.3.1/images/firefly_functionality_overview_tools.png new file mode 100644 index 000000000..42ee55dc2 Binary files /dev/null and b/v1.3.1/images/firefly_functionality_overview_tools.png differ diff --git a/v1.3.1/images/firefly_intro_overview.png b/v1.3.1/images/firefly_intro_overview.png new file mode 100644 index 000000000..28987c9aa Binary files /dev/null and b/v1.3.1/images/firefly_intro_overview.png differ diff --git a/v1.3.1/images/firefly_node.png b/v1.3.1/images/firefly_node.png new file mode 100644 index 000000000..51301c934 Binary files /dev/null and b/v1.3.1/images/firefly_node.png differ diff --git a/v1.3.1/images/firefly_orchestration_engine.png b/v1.3.1/images/firefly_orchestration_engine.png new file mode 100644 index 000000000..27635fa52 Binary files /dev/null and b/v1.3.1/images/firefly_orchestration_engine.png differ diff --git a/v1.3.1/images/firefly_plugin_architecture.jpg b/v1.3.1/images/firefly_plugin_architecture.jpg new file mode 100644 index 000000000..b5426eb0d Binary files /dev/null and b/v1.3.1/images/firefly_plugin_architecture.jpg differ diff --git a/v1.3.1/images/firefly_plugin_architecture.svg b/v1.3.1/images/firefly_plugin_architecture.svg new file mode 100644 index 000000000..c3e6a78ad --- /dev/null +++ b/v1.3.1/images/firefly_plugin_architecture.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/v1.3.1/images/firefly_stack.svg b/v1.3.1/images/firefly_stack.svg new file mode 100644 index 000000000..58a6283d5 --- /dev/null +++ b/v1.3.1/images/firefly_stack.svg @@ -0,0 +1,3 @@ + + + diff --git a/v1.3.1/images/firefly_transaction_manager.jpg b/v1.3.1/images/firefly_transaction_manager.jpg new file mode 100644 index 000000000..283a4ec8d Binary files /dev/null and b/v1.3.1/images/firefly_transaction_manager.jpg differ diff --git a/v1.3.1/images/firefly_transactions_explorer_view.png b/v1.3.1/images/firefly_transactions_explorer_view.png new file mode 100644 index 000000000..08b4ccdee Binary files /dev/null and b/v1.3.1/images/firefly_transactions_explorer_view.png differ diff --git a/v1.3.1/images/gateway_mode.png b/v1.3.1/images/gateway_mode.png new file mode 100644 index 000000000..20aba8ccd Binary files /dev/null and b/v1.3.1/images/gateway_mode.png differ diff --git a/v1.3.1/images/gateway_multiparty_mode.png b/v1.3.1/images/gateway_multiparty_mode.png new file mode 100644 index 000000000..99ba8e714 Binary files /dev/null and b/v1.3.1/images/gateway_multiparty_mode.png differ diff --git a/v1.3.1/images/getting-started-overview.png b/v1.3.1/images/getting-started-overview.png new file mode 100644 index 000000000..fe72b1af6 Binary files /dev/null and b/v1.3.1/images/getting-started-overview.png differ diff --git a/v1.3.1/images/global_sequencing.svg b/v1.3.1/images/global_sequencing.svg new file mode 100644 index 000000000..798e378a0 --- /dev/null +++ b/v1.3.1/images/global_sequencing.svg @@ -0,0 +1,2063 @@ + +image/svg+xmlFirefly CoreDB /BlobstoreMember 1AppIPFS /MessagingBlockchain Sequenced Messages/BatchesMember 1 Firefly NodeFirefly CoreDB /BlobstoreIPFS /MessagingMember 2 Firefly NodeEvent Stream1. Transaction submissionAn individual Firefly instance preserves the order that it received messages from application instances.Where possible, batching is used to roll- up 100s of transactions into a single blockchain transaction.Blockchain allows these messages to be globally sequenced with messages submitted by other members of the network.Green2. Blockchain locks in the orderAll member Firefly runtimes see every transaction., in the same sequence.This includes when transactions are being submitted by both sides concurrently.4. Events are processed consistently by all partiesAll firefly runtimes see every event that they are subscribed to, in the same sequence.The submitter must also apply the logic only in the sequence ordered by the blockchain. It cannot assume the order, just because it was the member who submitted it.3. Firefly assembles the complete original message in a queueA queue of events is maintained for each matching app subscription.The public/private data payloads travel separately to the blockchain, and arrive at different times. Firefly assembles these together before delivery.If data associated with a blockchain transaction is late, or does not arrive, all messages on the same"context" will be blocked.It is good practice to send messages that don't need to processed in order, with different "context" fields. For example use the ID of your business transaction, or other long- running process / customer identifier.Broadcast or Private transfer of dataMember 2AppFireFly Multi- PartyEvent SequencingRedBlueGreenEvent StreamGreenBlueRedRedBlueGreenRedBlue diff --git a/v1.3.1/images/hyperledger-firefly-namespaces-example-with-org.png b/v1.3.1/images/hyperledger-firefly-namespaces-example-with-org.png new file mode 100644 index 000000000..2076df4ee Binary files /dev/null and b/v1.3.1/images/hyperledger-firefly-namespaces-example-with-org.png differ diff --git a/v1.3.1/images/hyperledger-firefly_color.svg b/v1.3.1/images/hyperledger-firefly_color.svg new file mode 100644 index 000000000..395e207f4 --- /dev/null +++ b/v1.3.1/images/hyperledger-firefly_color.svg @@ -0,0 +1,142 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/v1.3.1/images/hyperledger_firefly_social.png b/v1.3.1/images/hyperledger_firefly_social.png new file mode 100644 index 000000000..b8ef2d4b1 Binary files /dev/null and b/v1.3.1/images/hyperledger_firefly_social.png differ diff --git a/v1.3.1/images/idempotency_keys_architecture.jpg b/v1.3.1/images/idempotency_keys_architecture.jpg new file mode 100644 index 000000000..fdb885dc9 Binary files /dev/null and b/v1.3.1/images/idempotency_keys_architecture.jpg differ diff --git a/v1.3.1/images/import_tokens.png b/v1.3.1/images/import_tokens.png new file mode 100644 index 000000000..985f43161 Binary files /dev/null and b/v1.3.1/images/import_tokens.png differ diff --git a/v1.3.1/images/internal_event_sequencing.jpg b/v1.3.1/images/internal_event_sequencing.jpg new file mode 100644 index 000000000..e5cb30737 Binary files /dev/null and b/v1.3.1/images/internal_event_sequencing.jpg differ diff --git a/v1.3.1/images/intro_to_firefly.png b/v1.3.1/images/intro_to_firefly.png new file mode 100644 index 000000000..3ae8d87a3 Binary files /dev/null and b/v1.3.1/images/intro_to_firefly.png differ diff --git a/v1.3.1/images/launch_config.png b/v1.3.1/images/launch_config.png new file mode 100644 index 000000000..40212bbaa Binary files /dev/null and b/v1.3.1/images/launch_config.png differ diff --git a/v1.3.1/images/message_broadcast_initial.png b/v1.3.1/images/message_broadcast_initial.png new file mode 100644 index 000000000..12af9b1fb Binary files /dev/null and b/v1.3.1/images/message_broadcast_initial.png differ diff --git a/v1.3.1/images/message_broadcast_sample_result.png b/v1.3.1/images/message_broadcast_sample_result.png new file mode 100644 index 000000000..c7f6ca466 Binary files /dev/null and b/v1.3.1/images/message_broadcast_sample_result.png differ diff --git a/v1.3.1/images/message_private_broadcast.png b/v1.3.1/images/message_private_broadcast.png new file mode 100644 index 000000000..7655518af Binary files /dev/null and b/v1.3.1/images/message_private_broadcast.png differ diff --git a/v1.3.1/images/metamask/account_address.png b/v1.3.1/images/metamask/account_address.png new file mode 100644 index 000000000..6837b6742 Binary files /dev/null and b/v1.3.1/images/metamask/account_address.png differ diff --git a/v1.3.1/images/metamask/add_network.png b/v1.3.1/images/metamask/add_network.png new file mode 100644 index 000000000..b6db864ee Binary files /dev/null and b/v1.3.1/images/metamask/add_network.png differ diff --git a/v1.3.1/images/metamask/contract_address.png b/v1.3.1/images/metamask/contract_address.png new file mode 100644 index 000000000..ec8852c38 Binary files /dev/null and b/v1.3.1/images/metamask/contract_address.png differ diff --git a/v1.3.1/images/metamask/import_tokens.png b/v1.3.1/images/metamask/import_tokens.png new file mode 100644 index 000000000..985f43161 Binary files /dev/null and b/v1.3.1/images/metamask/import_tokens.png differ diff --git a/v1.3.1/images/metamask/network_details.png b/v1.3.1/images/metamask/network_details.png new file mode 100644 index 000000000..64f29e772 Binary files /dev/null and b/v1.3.1/images/metamask/network_details.png differ diff --git a/v1.3.1/images/metamask/nft_contract_address.png b/v1.3.1/images/metamask/nft_contract_address.png new file mode 100644 index 000000000..2482ea172 Binary files /dev/null and b/v1.3.1/images/metamask/nft_contract_address.png differ diff --git a/v1.3.1/images/metamask/nft_token_balance.png b/v1.3.1/images/metamask/nft_token_balance.png new file mode 100644 index 000000000..70e08cb43 Binary files /dev/null and b/v1.3.1/images/metamask/nft_token_balance.png differ diff --git a/v1.3.1/images/metamask/send_tokens.png b/v1.3.1/images/metamask/send_tokens.png new file mode 100644 index 000000000..35910a534 Binary files /dev/null and b/v1.3.1/images/metamask/send_tokens.png differ diff --git a/v1.3.1/images/metamask/settings.png b/v1.3.1/images/metamask/settings.png new file mode 100644 index 000000000..c8408a05a Binary files /dev/null and b/v1.3.1/images/metamask/settings.png differ diff --git a/v1.3.1/images/metamask/tokens_received.png b/v1.3.1/images/metamask/tokens_received.png new file mode 100644 index 000000000..0d40f110e Binary files /dev/null and b/v1.3.1/images/metamask/tokens_received.png differ diff --git a/v1.3.1/images/multi_protocol.png b/v1.3.1/images/multi_protocol.png new file mode 100644 index 000000000..3cfbf79f4 Binary files /dev/null and b/v1.3.1/images/multi_protocol.png differ diff --git a/v1.3.1/images/multiparty_business_process_flow.jpg b/v1.3.1/images/multiparty_business_process_flow.jpg new file mode 100644 index 000000000..53e4c8b8a Binary files /dev/null and b/v1.3.1/images/multiparty_business_process_flow.jpg differ diff --git a/v1.3.1/images/multiparty_mode.png b/v1.3.1/images/multiparty_mode.png new file mode 100644 index 000000000..73c625e05 Binary files /dev/null and b/v1.3.1/images/multiparty_mode.png differ diff --git a/v1.3.1/images/multiparty_system1.png b/v1.3.1/images/multiparty_system1.png new file mode 100644 index 000000000..abdcbf7fd Binary files /dev/null and b/v1.3.1/images/multiparty_system1.png differ diff --git a/v1.3.1/images/network_details.png b/v1.3.1/images/network_details.png new file mode 100644 index 000000000..64f29e772 Binary files /dev/null and b/v1.3.1/images/network_details.png differ diff --git a/v1.3.1/images/new_message_view.png b/v1.3.1/images/new_message_view.png new file mode 100644 index 000000000..3d2b8b928 Binary files /dev/null and b/v1.3.1/images/new_message_view.png differ diff --git a/v1.3.1/images/nft_contract_address.png b/v1.3.1/images/nft_contract_address.png new file mode 100644 index 000000000..2482ea172 Binary files /dev/null and b/v1.3.1/images/nft_contract_address.png differ diff --git a/v1.3.1/images/nft_token_balance.png b/v1.3.1/images/nft_token_balance.png new file mode 100644 index 000000000..70e08cb43 Binary files /dev/null and b/v1.3.1/images/nft_token_balance.png differ diff --git a/v1.3.1/images/operations_by_transaction_type.jpg b/v1.3.1/images/operations_by_transaction_type.jpg new file mode 100644 index 000000000..7faa37187 Binary files /dev/null and b/v1.3.1/images/operations_by_transaction_type.jpg differ diff --git a/v1.3.1/images/ping_pong.jpg b/v1.3.1/images/ping_pong.jpg new file mode 100644 index 000000000..a76220495 Binary files /dev/null and b/v1.3.1/images/ping_pong.jpg differ diff --git a/v1.3.1/images/ping_pong.svg b/v1.3.1/images/ping_pong.svg new file mode 100644 index 000000000..46941b54f --- /dev/null +++ b/v1.3.1/images/ping_pong.svg @@ -0,0 +1,5027 @@ + +image/svg+xmlData Exchange Use Case1. Broadcast Public Description of binary data assetUpload Blob of the actual dataGives you a hash of that dataUpload JSON containing the public index dataInclude the hash of the full dataSend a broadcast message with the public index dataAgree a primary key of the data as the context2. Receive Public Description and request Asset Data via blockchain- pinned requestStore data in your own database, for rich queryRun automated logic to decide if you want the full dataUpload JSON for the data requestSend a private messageBacked by blockchain in this exampleMember 1Member 23. Authorize and Transfer dataInspect the request dataRetrieve data asset by hashSend the private data in a private messageNo blockchain in this exampleFireflyFireflyCoreRemoteAgentsUtilityServicesDataManagerDataExchangeAppStoreJSONDataManagerStoreBlobBlobStoreStoreAsset DataStoreDescriptionhashEventManagerSendBroadcastBroadcastMessage (pinned)combinableIPFSBlockchainInterfaceBlockchainNodeFireflyUtilityServicesRemoteAgentsFireflyCoreBlockchainNodeMessage (batched)BlockchainInterfaceDataAggregatorDataExchangeIPFSData (batched)EventDispatcherBroadcast Manager(batching)SubsciptionManagerWebsocketEvent ProcessorAppStore forrich queryTriggerEventProcessevent dataStoredata requestDataManagerStoreJSONcombinablePrivate MessagingManagerPrivate send(pinned)Send PrivateMessage (pinned)DatabaseDatabasePrivateMessagingBlockchainInterfaceBlockchainNodeWebsocketEvent ProcessorCommitEventEventDispatcherFireflyFireflyCoreRemoteAgentsUtilityServicesAppBlockchainNodePrivateMessagingDataMessageDataAggregatorEventDispatcherSubsciptionManagerBlockchainInterfaceDataExchangeWebsocketEvent ProcessorProcessrequest dataPrivate send binary (unpinned)DoneDonePrivate MessagingManagerManagedFile XferWebsocketEvent ProcessorEventDispatcherCommitEventSend PrivateMessage (unpinned)TriggerEventBlockchain pinnedBroadcastBlockchain pinnedPrivate MessageFireflyUtilityServicesRemoteAgentsFireflyCoreAppBlobStoreManagedFile XferDataDataExchangeDataAggregatorEventDispatcherSubsciptionManagerWebsocketEvent ProcessorStore/use JSONdata + Blob URLTriggerEventDoneWebsocketEvent ProcessorCommitEventEventDispatcherBlobStore4. Receive data assetReceive a link to your local copy of the asset dataPrivate messagewith large dataattachmentBlobStoreDataManagerStoreJSONStoreTransfer msgcombinableDatabaseDataExchangeDataExchangePrivateMessagingPrivate messagingMessage + DataDataExchangeDataExchange diff --git a/v1.3.1/images/problem_statement.png b/v1.3.1/images/problem_statement.png new file mode 100644 index 000000000..bf2797f0c Binary files /dev/null and b/v1.3.1/images/problem_statement.png differ diff --git a/v1.3.1/images/releases.png b/v1.3.1/images/releases.png new file mode 100644 index 000000000..a86a30c90 Binary files /dev/null and b/v1.3.1/images/releases.png differ diff --git a/v1.3.1/images/sandbox/sandbox_api_swagger.png b/v1.3.1/images/sandbox/sandbox_api_swagger.png new file mode 100644 index 000000000..ba51a707e Binary files /dev/null and b/v1.3.1/images/sandbox/sandbox_api_swagger.png differ diff --git a/v1.3.1/images/sandbox/sandbox_broadcast.png b/v1.3.1/images/sandbox/sandbox_broadcast.png new file mode 100644 index 000000000..a1c025187 Binary files /dev/null and b/v1.3.1/images/sandbox/sandbox_broadcast.png differ diff --git a/v1.3.1/images/sandbox/sandbox_broadcast_result.png b/v1.3.1/images/sandbox/sandbox_broadcast_result.png new file mode 100644 index 000000000..a2b7cfa91 Binary files /dev/null and b/v1.3.1/images/sandbox/sandbox_broadcast_result.png differ diff --git a/v1.3.1/images/sandbox/sandbox_contracts_api.png b/v1.3.1/images/sandbox/sandbox_contracts_api.png new file mode 100644 index 000000000..0690b937b Binary files /dev/null and b/v1.3.1/images/sandbox/sandbox_contracts_api.png differ diff --git a/v1.3.1/images/sandbox/sandbox_token_pool.png b/v1.3.1/images/sandbox/sandbox_token_pool.png new file mode 100644 index 000000000..dc92631fa Binary files /dev/null and b/v1.3.1/images/sandbox/sandbox_token_pool.png differ diff --git a/v1.3.1/images/sandbox/sandbox_token_transfer_result.png b/v1.3.1/images/sandbox/sandbox_token_transfer_result.png new file mode 100644 index 000000000..bdd7e384c Binary files /dev/null and b/v1.3.1/images/sandbox/sandbox_token_transfer_result.png differ diff --git a/v1.3.1/images/send_tokens.png b/v1.3.1/images/send_tokens.png new file mode 100644 index 000000000..35910a534 Binary files /dev/null and b/v1.3.1/images/send_tokens.png differ diff --git a/v1.3.1/images/settings.png b/v1.3.1/images/settings.png new file mode 100644 index 000000000..c8408a05a Binary files /dev/null and b/v1.3.1/images/settings.png differ diff --git a/v1.3.1/images/simple_storage_swagger.png b/v1.3.1/images/simple_storage_swagger.png new file mode 100644 index 000000000..95b422ec1 Binary files /dev/null and b/v1.3.1/images/simple_storage_swagger.png differ diff --git a/v1.3.1/images/smart_contracts_async_flow.svg b/v1.3.1/images/smart_contracts_async_flow.svg new file mode 100644 index 000000000..89634efa7 --- /dev/null +++ b/v1.3.1/images/smart_contracts_async_flow.svg @@ -0,0 +1 @@ +title%20Smart%20Contracts%20Async%20Flow%0A%0AApp-%3EFireFly%3A%20Invoke%20custom%20contract%0AFireFly-%3EBlockchain%3A%20Submit%20transaction%0ABlockchain-%3EFireFly%3A%20Accepted%0AFireFly-%3EApp%3A%20Accepted%5Cn(Operation%20ID)%0ABlockchain-%3EBlockchain%3A%20Perform%20transaction%0ABlockchain-%3EFireFly%3A%20Emit%20events%0AFireFly-%3EApp%3A%20Emit%20eventsSmart Contracts Async FlowAppFireFlyBlockchainInvoke custom contractSubmit transactionAcceptedAccepted(Operation ID)Perform transactionEmit eventsEmit events \ No newline at end of file diff --git a/v1.3.1/images/tokens_received.png b/v1.3.1/images/tokens_received.png new file mode 100644 index 000000000..0d40f110e Binary files /dev/null and b/v1.3.1/images/tokens_received.png differ diff --git a/v1.3.1/images/understanding_firefly1.png b/v1.3.1/images/understanding_firefly1.png new file mode 100644 index 000000000..24ab63908 Binary files /dev/null and b/v1.3.1/images/understanding_firefly1.png differ diff --git a/v1.3.1/images/websocket_example.png b/v1.3.1/images/websocket_example.png new file mode 100644 index 000000000..cb2ffb236 Binary files /dev/null and b/v1.3.1/images/websocket_example.png differ diff --git a/v1.3.1/index.html b/v1.3.1/index.html new file mode 100644 index 000000000..5e64e894c --- /dev/null +++ b/v1.3.1/index.html @@ -0,0 +1,3382 @@ + + + + + + + + + + + + + + + + + + + + + Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Hyperledger FireFly

+

Hyperledger FireFly

+

Hyperledger FireFly is an open source Supernode, a complete stack for enterprises to build and scale secure Web3 applications.

+

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.

+

Head to the Understanding FireFly section for more details.

+ + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/gateway_features/index.html b/v1.3.1/overview/gateway_features/index.html new file mode 100644 index 000000000..c0cb61db8 --- /dev/null +++ b/v1.3.1/overview/gateway_features/index.html @@ -0,0 +1,3628 @@ + + + + + + + + + + + + + + + + + + + + + + + Web3 Gateway Features - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Web3 Gateway Features

+ +

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.

+

Gateway Mode

+

Transfer tokenized value

+

The Digital Asset Features allow you to connect to +token economies, in multiple blockchains, using the same infrastructure and signing keys.

+

The complexities of how each token works, and how each blockchain works, are abstracted +away from you by the Hyperledger FireFly Connector Framework.

+

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.

+

Invoke any other type of smart contract

+

The API Generation features of Hyperledger FireFly, allow +you to generate a convenient and reliable REST API for any smart contract logic.

+

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.

+

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.

+
    +
  • Handles peaks in workload, drip-feeding transactions onto the chain
    • +
  • Handles large batch submissions, tracking
    • +
  • Manages nonce assignment at high volume
    • +
  • Idempotent APIs assuring that business transactions are submitted exactly once
    • +
+
+

For EVM based chains, these features were significantly enhanced in the new EVMConnect +connector introduced in v1.1 of FireFly (superseding EthConnect).

+
+

Index data from the blockchain

+

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.

+

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.

+

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.

+

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.

+

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.

+

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.

+

Reliably trigger events in your applications

+

One of the most important universal rules about Web3 applications, is that they are event-driven.

+

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.

+

This means the integration into your application and core systems needs to be event-driven too.

+

The same features that support reliable indexing of the blockchain data, allow reliable triggering +of application code, business workflows, and core system integrations.

+
+

Learn more about the FireFly Event Bus

+
+

Manage decentralized data (NFTs etc.)

+

Your blockchain transactions are likely to refer to data that is stored off-chain.

+

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.

+

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.

+

Structured JSON data can be stored, uploaded and downloaded from the FireFly database.

+

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.

+

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.

+

Maintain a private address book

+

You need to manage your signing keys, and know the signing keys of others you are +transacting with. A blockchain address like 0x0742e81393ee79C768e84cF57F1bF314F0f31ECe +is not very helpful for this.

+

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.

+

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.

+
+

Learn more about Hyperledger FireFly Identities

+
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/key_components/apps/index.html b/v1.3.1/overview/key_components/apps/index.html new file mode 100644 index 000000000..60b2ea6ae --- /dev/null +++ b/v1.3.1/overview/key_components/apps/index.html @@ -0,0 +1,3578 @@ + + + + + + + + + + + + + + + + + + + + + + + Apps - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Apps

+ +

Hyperledger FireFly App Features

+

Apps

+

Rapidly accelerating development of applications is a key feature of Hyperledger FireFly.

+

The toolkit is designed to support the full-stack of applications in the enterprise Web3 +ecosystem, not just the Smart Contract layer.

+

Business logic APIs, back-office system integrations, and web/mobile user experiences are just +as important to the overall Web3 use case.

+

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.

+

API Gateway

+

FireFly provides APIs that:

+
    +
  • Are fast and efficient
    • +
  • Have rich query support
    • +
  • Give deterministic outcomes and clear instructions for safe use
    • +
  • Integrate with your security frameworks like OAuth 2.0 / OpenID Connect single sign-on
    • +
  • Provide Open API 3 / Swagger definitions
    • +
  • Come with code SDKs, with rich type information
    • +
  • Conform as closely as possible to the principles of REST
    • +
  • Do not pretend to be RESTful in cases when it is impossible to be
    • +
+
+

Learn more about deploying APIs for custom smart contracts in this tutorial

+
+

Event Streams

+

The reality is that the only programming paradigm that works for a decentralized solutions, +is an event-driven one.

+

All blockchain technologies are for this reason event-driven programming interfaces at their core.

+

In an overall solution, those on-chain events must be coordinated with off-chain private +data transfers, and existing core-systems / human workflows.

+

This means great event support is a must:

+
    +
  • Convenient WebSocket APIs that work for your microservices development stack
    • +
  • Support for Webhooks to integrated serverless functions
    • +
  • Integration with your core enterprise message queue (MQ) or enterprise service bus (ESB)
    • +
  • At-least-once delivery assurance, with simple instructions at the application layer
    • +
+
+

Learn all about the Hyperledger FireFly Event Bus, and event-driven application architecture, +in this reference section

+
+

API Generation

+

The blockchain is going to be at the heart of your Web3 project. While usually small in overall surface +area compared to the lines of code in the traditional application tiers, this kernel of +mission-critical code is what makes your solution transformational compared to a centralized / Web 2.0 solution.

+

Whether the smart contract is hand crafted for your project, an existing contract on a public blockchain, +or a built-in pattern of a framework like FireFly - it must be interacted with correctly.

+

So there can be no room for misinterpretation in the hand-off between the blockchain +Smart Contract specialist, familiar with EVM contracts in Solidity/Vyper, Fabric chaincode +(or maybe even raw block transition logic in Rust or Go), and the backend / full-stack +application developer / core-system integrator.

+

Well documented APIs are the modern norm for this, and it is no different for blockchain.

+

This means Hyperledger FireFly provides:

+
    +
  • Generating the interface for methods and events on your smart contract
    • +
  • Providing robust transaction submission, and event streaming
    • +
  • Publishing the API, version, and location, of your smart contracts to the network
    • +
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/key_components/connectors/index.html b/v1.3.1/overview/key_components/connectors/index.html new file mode 100644 index 000000000..2e5de0b3d --- /dev/null +++ b/v1.3.1/overview/key_components/connectors/index.html @@ -0,0 +1,3518 @@ + + + + + + + + + + + + + + + + + + + + + + + Connector Framework - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Connector Framework

+ +

Hyperledger FireFly Connectivity Features

+

Pluggable Microservices Architecture

+

The ability for every component to be pluggable is at the core of Hyperledger FireFly.

+

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.

+

Hyperledger FireFly Architecture Overview

+

Extension points

+
    +
  • Blockchain - a rich framework for extensibility to any blockchain / digital ledger technology (DLT)
    • +
  • Tokens - mapping token standards and governance models to a common data model
    • +
  • Shared storage - supporting permissioned and public distributed storage technologies
    • +
  • Data exchange - private local/storage and encrypted transfer of data
    • +
  • Identity - flexibility for resolving identities via Decentralized IDentifier (DID)
    • +
  • Persistence - the local private database
    • +
+
+

Learn more about the plugin architecture here

+
+

Blockchain Connector Framework

+

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.

+

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.

+
+

Check out instructions to connect to a list of remote blockchain networks here.

+
+

FireFly Blockchain Connector Framework

+

Find out more about the Blockchain Connector Framework here.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/key_components/digital_assets/index.html b/v1.3.1/overview/key_components/digital_assets/index.html new file mode 100644 index 000000000..9e10ebe5c --- /dev/null +++ b/v1.3.1/overview/key_components/digital_assets/index.html @@ -0,0 +1,3568 @@ + + + + + + + + + + + + + + + + + + + + + + + Digital Assets - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Digital Assets

+ +

Hyperledger FireFly Digital Asset Features

+

Digital asset features

+

The modelling, transfer and management of digital assets is the core programming +foundation of blockchain.

+

Yet out of the box, raw blockchains designed to efficiently manage these assets +in large ecosystems, do not come with all the building blocks needed by applications.

+

Token API

+

Token standards have been evolving in the industry through standards +like ERC-20/ERC-721, and the Web3 signing wallets that support these.

+

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.

+

This means one application or set of back-end systems, can integrate with multiple +blockchains, and different token implementations.

+

Pluggability here is key, so that the rules of governance of each digital +asset ecosystem can be exposed and enforced. Whether tokens are fungible, +non-fungible, or some hybrid in between.

+
+

Learn more about token standards for fungible tokens, and non-fungible +tokens (NFTs) in this set of tutorials

+
+

Transfer history / audit trail

+

For efficiency blockchains do not provide a direct ability to +query historical transaction information.

+

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.

+

So off-chain indexing of transaction history is an absolute must-have +for any digital asset solution.

+

Hyperledger FireFly provides:

+
    +
  • Automatic indexing of tokens, whether existing or newly deployed
    • +
  • Off-chain indexing of fungible and non-fungible asset transfers & balances
    • +
  • Off-chain indexing of approvals
    • +
  • Integration with digital identity
    • +
  • Full extensibility across both token standards and blockchain technologies
    • +
+

Wallets

+

Wallet and signing-key management is a critical requirement for any +blockchain solution, particularly those involving the transfer +of digital assets between wallets.

+

Hyperledger FireFly provides you the ability to:

+
    +
  • Integrate multiple different signing/custody solutions in a proven way
    • +
  • Manage the mapping of off-chain identities to on-chain signing identities
    • +
  • Provide a plug-point for policy-based decision making on high value transactions
    • +
  • Manage connections to multiple different blockchain solutions
    • +
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/key_components/flows/index.html b/v1.3.1/overview/key_components/flows/index.html new file mode 100644 index 000000000..9149e9f2f --- /dev/null +++ b/v1.3.1/overview/key_components/flows/index.html @@ -0,0 +1,3601 @@ + + + + + + + + + + + + + + + + + + + + + + + Flows - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Flows

+ +

Hyperledger FireFly Data Flow Features

+

Data flow

+

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.

+

Some additional data flow is always required. This does not diminish the value of +executing the kernel of the logic within the blockchain itself.

+

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.

+

Let's look at a few common examples:

+

Digital Asset Transfers

+

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.

+

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?

+

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.

+

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.

+
+

A common form of digital escrow is a Hashed Timelock Contract (HTLC).

+
+

Non-fungible Tokens (NFTs) and hash-pinning

+

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.

+

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.

+

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.

+

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.

+

Dynamic NFTs and Business Transaction Flow

+

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.

+

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.

+

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.

+

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.

+

Data and Transaction Flow patterns

+

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.

+

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:

+
    +
  • Coordinating the transfer of data off-chain with a blockchain sequencing transaction
    • +
  • Batching for high throughput transfer via the blockchain and distributed storage technologies
    • +
  • Managing privacy groups between parties involved in a business transaction
    • +
  • Masking the relationship between blockchain transactions, for sensitive data
    • +
+

Multi-party business process flow

+
+

Learn more in Multiparty Process Flows

+
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/key_components/index.html b/v1.3.1/overview/key_components/index.html new file mode 100644 index 000000000..94bdb1d6a --- /dev/null +++ b/v1.3.1/overview/key_components/index.html @@ -0,0 +1,3390 @@ + + + + + + + + + + + + + + + + + + + + + + + Key Features - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Key Features

+ +

Hyperledger FireFly features

+

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.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/key_components/orchestration_engine/index.html b/v1.3.1/overview/key_components/orchestration_engine/index.html new file mode 100644 index 000000000..eba284148 --- /dev/null +++ b/v1.3.1/overview/key_components/orchestration_engine/index.html @@ -0,0 +1,3524 @@ + + + + + + + + + + + + + + + + + + + + + + + Orchestration Engine - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Orchestration Engine

+ +

Hyperledger FireFly Orchestration Engine

+

FireFly Core

+

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.

+

Hyperledger FireFly Orchestration Engine

+

Data Layer

+

Your own private view of the each network you connect:

+
    +
  • Indexes of all tokens and NFTs that you transact with
    • +
  • A consistent view across multiple blockchains
    • +
  • High performance rich query of transaction and data audit trail
    • +
  • Private data you have received from other parties
    • +
  • Local copies of data you have download from IPFS or other shared storage tech
    • +
+

Event Bus

+

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:

+

Decentralized applications are event-driven.

+

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.

+

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.

+
    +
  • Token transfer events, across multiple blockchains, and varied asset types
    • +
  • Custom smart contract events
    • +
  • Correlated on-chain and off-chain data events
    • +
+

Hyperledger FireFly Event Mode

+
+

Learn more about the event bus and event-driven programming in this +reference document

+
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/key_components/security/index.html b/v1.3.1/overview/key_components/security/index.html new file mode 100644 index 000000000..c957edd27 --- /dev/null +++ b/v1.3.1/overview/key_components/security/index.html @@ -0,0 +1,3526 @@ + + + + + + + + + + + + + + + + + + + + + + + Security - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Security

+ +

Hyperledger FireFly Security Features

+

API Security

+

Hyperledger FireFly provides a pluggable infrastructure for authenticating API requests.

+

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.

+

A reference plugin implementation is provided for HTTP Basic Auth, combined with a htpasswd +verification of passwords with a bcrypt encoding.

+

See this config section for details, and the +reference implementation +in Github

+
+

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.

+
+

Data Partitioning and Tenancy

+

Namespaces also provide a data isolation system for different +applications / teams / tenants sharing a Hyperledger FireFly node.

+

Namespaces

+

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.

+

Private Data Exchange

+

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 & documents.

+

Hyperledger FireFly Data Transport Layers

+

A reference microservice implementation is provided for HTTPS point-to-point connectivity with +mutual TLS encryption.

+

See the reference implementation +in Github

+
+

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.

+
+

Learn more about these private data flows in Multiparty Process Flows.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/key_components/tools/index.html b/v1.3.1/overview/key_components/tools/index.html new file mode 100644 index 000000000..3cc905d0e --- /dev/null +++ b/v1.3.1/overview/key_components/tools/index.html @@ -0,0 +1,3503 @@ + + + + + + + + + + + + + + + + + + + + + + + Tools - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Tools

+ +

Hyperledger FireFly Tools

+

FireFly CLI

+

FireFly CLI

+

The FireFly CLI can be used to create local FireFly stacks for offline development of blockchain apps. This allows developers to rapidly iterate on their idea without needing to set up a bunch of infrastructure before they can write the first line of code.

+

FireFly Sandbox

+

FireFly Sandbox

+

The FireFly Sandbox sits logically outside the Supernode, and it acts like an "end-user" application written to use FireFly's API. In your setup, you have one Sandbox per member, each talking to their own FireFly API. The purpose of the Sandbox is to provide a quick and easy way to try out all of the fundamental building blocks that FireFly provides. It also shows developers, through example code snippets, how they would implement the same functionality in their own app's backend.

+
+

🗒 Technical details: The FireFly Sandbox is an example "full-stack" web app. It has a backend written in TypeScript / Node.js, and a frontend in TypeScript / React. When you click a button in your browser, the frontend makes a request to the backend, which then uses the FireFly Node.js SDK to make requests to FireFly's API.

+
+

FireFly Explorer

+

The FireFly explorer is a part of FireFly Core itself. It is a view into the system that allows operators to monitor the current state of the system and investigate specific transactions, messages, and events. It is also a great way for developers to see the results of running their code against FireFly's API.

+

FireFly Explorer

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/multiparty/broadcast/index.html b/v1.3.1/overview/multiparty/broadcast/index.html new file mode 100644 index 000000000..344fe731c --- /dev/null +++ b/v1.3.1/overview/multiparty/broadcast/index.html @@ -0,0 +1,3558 @@ + + + + + + + + + + + + + + + + + + + + + + + Broadcast / shared data - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Broadcast / shared data

+ +

Introduction

+

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

+

Multi-party Systems

+

Blockchain backed broadcast

+

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.

+

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.

+

For more information see Multiparty Event Sequencing.

+

Shared data

+

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.

+

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.

+

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.

+

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.

+

FireFly built-in broadcasts

+

FireFly uses the broadcast mechanism internally to distribute key information to +all parties in the network:

+
    +
  • Network map
    • +
  • Organizational identities
    • +
  • Nodes
    • +
  • See Identities in the reference section for more information
    • +
  • Datatype definitions
    • +
  • See Datatype in the reference section for more information
    • +
  • Namespaces
    • +
  • See Namespaces for more information
    • +
+

These definitions rely on the same assurances provided by blockchain backed +broadcast that FireFly applications do.

+
    +
  • Verification of the identity of the party in the network that performed the broadcast
    • +
  • Deterministic assignment of a namespace+name to an unique item of data
    • +
  • 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)
    • +
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/multiparty/data_exchange/index.html b/v1.3.1/overview/multiparty/data_exchange/index.html new file mode 100644 index 000000000..303856dea --- /dev/null +++ b/v1.3.1/overview/multiparty/data_exchange/index.html @@ -0,0 +1,3546 @@ + + + + + + + + + + + + + + + + + + + + + + + Private data exchange - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Private data exchange

+ +

Introduction

+

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.

+

Multi-party Systems

+

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.

+

So real-time application to application private messaging, and private +transfer of large blobs/documents, are first class constructs in the FireFly API.

+

Qualities of service

+

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.

+
    +
  • Transport Encryption
    • +
  • 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.
    • +
  • Authentication
    • +
  • 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.
    • +
  • 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).
    • +
  • Request/Response (Sync) vs. Message Queuing (Async)
    • +
  • 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.
    • +
  • 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.
    • +
  • Hub & spoke vs. Peer to peer
    • +
  • 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.
    • +
  • End-to-end Payload Encryption
    • +
  • 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.
    • +
  • Large blob / Managed file transfer
    • +
  • 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.
    • +
+

FireFly OSS implementation

+

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.

+

See hyperledger/firefly-dataexchange-https

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/multiparty/deterministic/index.html b/v1.3.1/overview/multiparty/deterministic/index.html new file mode 100644 index 000000000..472c26ebb --- /dev/null +++ b/v1.3.1/overview/multiparty/deterministic/index.html @@ -0,0 +1,3598 @@ + + + + + + + + + + + + + + + + + + + + + + + Deterministic Compute - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Deterministic Compute

+ +

Introduction

+

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.

+

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.

+

The more sophisticated the agreement is you want to prove, the more consideration needs +to be taken into factors such as:

+
    +
  • Data privacy
    • +
  • Data deletion
    • +
  • Ease of understanding by business users
    • +
  • Ease of audit
    • +
  • Autonomy of parties with proprietary business logic
    • +
  • Human workflows (obviously non-deterministic)
    • +
  • Technology complexity/maturity (particularly for privacy preserving technologies)
    • +
  • Cost and skills for implementation
    • +
+

FireFly embraces the fact that different use cases, will make different decisions on how much +of the agreement should be enforced through deterministic compute.

+

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.

+

The fundamental building blocks

+

There are some fundamental types of deterministic computation, that can be proved with +mature blockchain technology, and all multi-party systems should consider exploiting:

+
    +
  • Total conservation of value
    • +
  • Allows you to assign value to something, because you know it is a fraction of a total pool
    • +
  • This is the magic behind fungible tokens, or "coins"
    • +
  • The proven technology for this is a shared ledger of all previous transactions
    • +
  • Learn more in the Tokens section
    • +
  • Existence and ownership of a unique identifiable thing
    • +
  • Gives you an anchor to attach to something in the real world
    • +
  • This is the magic behind non-fungible tokens (NTFs)
    • +
  • The proven technology for this is a shared ledger of its creation, and ownership changes
    • +
  • Learn more in the Tokens section
    • +
  • An agreed sequence of events
    • +
  • The foundation tool that allows the building of higher level constructs (including tokens)
    • +
  • Not previously available when business ecosystems used HTTP/Messaging transports alone
    • +
  • Can be bi-lateral, multi-lateral or global
    • +
  • Each blockchain technology has different features to establish these "chains" of information
    • +
  • Different approaches provide privacy different levels of privacy on the parties and sequence
    • +
  • Identification of data by a "hash" of its contents
    • +
  • The glue that binds a piece of private data, to a proof that you have a copy of that data
    • +
  • This is the basis of "pinning" data to the blockchain, without sharing its contents
    • +
  • Care needs to be taken to make sure the data is unique enough to make the hash secure
    • +
  • Learn more in the Gateway Features section
    • +
+

Advanced Cryptography and Privacy Preserving Trusted Compute

+

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.

+

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.

+

Technologies exist that can solve these requirements, with two major categories:

+
    +
  • Zero Knowledge Proofs (ZKPs)
    • +
  • 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.
    • +
  • Trusted Compute Environments (TEEs)
    • +
  • 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.
    • +
+

FireFly today provides an orchestration engine that's helpful in coordinating the inputs, outputs, +and execution of such advanced cryptography technologies.

+

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.

+

Complementary approaches to deterministic computation

+

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.

+

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.

+

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.

+

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.

+

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.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/multiparty/index.html b/v1.3.1/overview/multiparty/index.html new file mode 100644 index 000000000..1af21e751 --- /dev/null +++ b/v1.3.1/overview/multiparty/index.html @@ -0,0 +1,3467 @@ + + + + + + + + + + + + + + + + + + + + + + + Multiparty Features - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Enterprise multi-party systems

+

Introduction

+

Multiparty mode has all the features in Gateway mode with the added benefit of multi-party process flows.

+

A multi-party system is a class of application empowered by the technology revolution +of blockchain digital ledger technology (DLT), and emerging cryptographic proof technologies +like zero-knowledge proofs (ZKPs) and trusted execution environments (TEEs).

+

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.

+

Multiparty Mode

+

Through agreement on a common source of truth, such as the completion of a step in a +business process to proceed, or the existence and ownership of a unique asset, businesses +can cut out huge inefficiencies in existing multi-party processes.

+

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.

+

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.

+

Points of difference

+

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.

+

Multi-party systems are different from centralized third-party systems, because each +party retains sovereignty over:

+
    +
  • Their application instance
    • +
  • Their private data
    • +
  • Their business processes
    • +
  • Their proprietary business logic
    • +
  • Their internal business processes and IT controls
    • +
+

Use Case Example

+

There are many multiparty use cases. An example for healthcare is detailed below.

+

Patient care requires multiple entities to work together including healthcare providers, insurance companies, and medical systems. Sharing data between these parties is inefficient and prone to errors and patient information must be kept secure and up to date. Blockchain's shared ledger makes it possible to automate data sharing while ensuring accuracy and privacy.

+

In a Multi-party FireFly system, entities are able to share data privately as detailed in the "Data Exchange" section. For example, imagine a scenario where there is 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.

+

In a larger healthcare ecosystem with many members, a similar concept may emerge with multiple variations of members.

+ + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/multiparty/multiparty_flow/index.html b/v1.3.1/overview/multiparty/multiparty_flow/index.html new file mode 100644 index 000000000..180ddbefc --- /dev/null +++ b/v1.3.1/overview/multiparty/multiparty_flow/index.html @@ -0,0 +1,3685 @@ + + + + + + + + + + + + + + + + + + + + + + + Multiparty Process Flows - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Multiparty Process Flows

+ +

Flow features

+

Data, value, and process flow are how decentralized systems function. In an enterprise context +not all of this data can be shared with all parties, and some is very sensitive.

+

Private data flow

+

Managing the flows of data so that the right information is shared with the right parties, +at the right time, means thinking carefully about what data flows over what channel.

+

The number of enterprise solutions where all data can flow directly through the blockchain, +is vanishingly small.

+

Coordinating these different data flows is often one of the biggest pieces of heavy lifting solved +on behalf of the application by a robust framework like FireFly:

+
    +
  • Establishing the identity of participants so data can be shared
    • +
  • Securing the transfer of data off-chain
    • +
  • Coordinating off-chain data flow with on-chain data flow
    • +
  • Managing sequence for deterministic outcomes for all parties
    • +
  • Integrating off-chain private execution with multi-step stateful business logic
    • +
+

Multi-party business process flow

+

Web3 has the potential to transform how ecosystems interact. Digitally transforming +legacy process flows, by giving deterministic outcomes that are trusted by all parties, +backed by new forms of digital trust between parties.

+

Some of the most interesting use cases require complex multi-step business process across +participants. The Web3 version of business process management, comes with a some new challenges.

+

So you need the platform to:

+
    +
  • Provide a robust event-driven programming model fitting a "state machine" approach
    • +
  • Integrate with the decentralized application stack of each participant
    • +
  • Allow integration with the core-systems and human decision making of each participant
    • +
  • Provide deterministic ordering between all parties
    • +
  • Provide identity assurance and proofs for data flow / transition logic
    • +
+

Data exchange

+

Business processes need data, and that data comes in many shapes and sizes.

+

The platform needs to handle all of them:

+
    +
  • Large files and documents, as well as application data
    • +
  • Uniqueness / Enterprise NFTs - agreement on a single "foreign key" for a record
    • +
  • Non-repudiation, and acknowledgement of receipt
    • +
  • Coordination of flows of data, with flows of value - delivery vs. payment scenarios
    • +
+

Building multi-party flows

+

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.

+

Multi-party business process flow

+
    +
  • Build multi-party business processes where there is one agreed outcome:
    • +
  • Agree the trigger, inputs, outputs of each step in the process
    • +
  • Agree any common "rules of the road" must be adhered to
    • +
  • Look back at your shared history, when deciding to commit to the next step:
    • +
  • Fast rich-query cache, backed by a private database
    • +
  • Initiate the next step through automated or manual decision making
    • +
  • Only consider a step final once it's multi-party sequence has been confirmed
    • +
  • Gain big efficiencies in how multi-party business processes work:
    • +
  • Once locked in, a step is consider final - attested to by the party
    • +
  • If two parties submit conflicting actions, one wins, and one loses
    • +
  • Avoids complex compensation logic in the business orchestration layer
    • +
  • Provides one clear source of truth to quickly resolve multi-party disputes
    • +
  • Program multi-party apps using the tools you know:
    • +
  • REST APIs for triggering the next step in a process, and querying history
    • +
  • WebSockets and Webhooks for events (pluggable to other event transports)
    • +
  • Remember - each party runs their own copy of the app, with their own private data
    • +
  • Allow each party to integrate into their existing core systems:
    • +
  • Realtime or batch
    • +
  • Human workflows
    • +
  • Proprietary business logic that is unique to one party
    • +
  • Avoid sensitive data written to the blockchain:
    • +
  • Works in bi-lateral and multi-lateral scenarios
    • +
  • Designed to limit leaking other "metadata" about the transaction as well
    • +
  • Share partial history with different participants in a
    • +
  • No requirement to write custom on-chain smart contract logic:
    • +
  • Can be combined with rich custom on-chain logic as well
    • +
+

Innovate fast

+

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.

+

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.

+

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.

+

Consider the on-chain toolbox too

+

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.

+

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.

+

On top of this you can add advanced tools like digital escrow, signature / threshold based voting +on outcomes, and atomic swaps of value/ownership.

+

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.

+

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.

+
+

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.

+
+

Learn more in the Deterministic Compute section.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/public_vs_permissioned/index.html b/v1.3.1/overview/public_vs_permissioned/index.html new file mode 100644 index 000000000..f466da3f4 --- /dev/null +++ b/v1.3.1/overview/public_vs_permissioned/index.html @@ -0,0 +1,3596 @@ + + + + + + + + + + + + + + + + + + + + + + + Public and Permissioned - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Public and Permissioned Blockchain

+

Public and Permissioned Blockchains

+

A separate choice to the technology for your blockchain, is what combination +of blockchain ecosystems you will integrate with.

+

There are a huge variety of options, and increasingly you might find yourself +integrating with multiple ecosystems in your solutions.

+

A rough (and incomplete) high level classification of the blockchains available is as follows:

+
    +
  • Layer 1 public blockchains
    • +
  • This is where most token ecosystems are rooted
    • +
  • Layer 2 public scaling solutions backed by a Layer 1 blockchain
    • +
  • These are increasing where transaction execution takes place that + needs to be reflected eventually back to a Layer 1 blockchain (due + to cost/congestion in the Layer 1 chains)
    • +
  • Permissioned side-chains
    • +
  • Historically this has been where the majority of production adoption of + enterprise blockchain has focussed, due to the predictable cost, performance, + and ability to manage the validator set and boundary API security + alongside a business network governance policy
    • +
  • These might have their state check-pointed/rolled-up to a Layer 2 or Layer 1 chain
    • +
+

The lines are blurring between these categorizations as the technologies and ecosystems evolve.

+

Public blockchain variations

+

For the public Layer 1 and 2 solutions, there are too many subclassifications to go into in detail here:

+
    +
  • Whether ecosystems supports custom smart contract execution (EVM based is most common, where contracts are supported)
    • +
  • What types of token standards are supported, or other chain specific embedded smart contracts
    • +
  • Whether the chain follows an unspent transaction output (UTXO) or Account model
    • +
  • How value is bridged in-to / out-of the ecosystem
    • +
  • How the validator set of the chain is established - most common is Proof of Stake (PoS)
    • +
  • How data availability is maintained - to check the working of the validators ensure the historical state is not lost
    • +
  • The consensus algorithm, and how it interacts with the consensus of other blockchains
    • +
  • How state in a Layer 2 is provable in a parent Layer 1 chain (rollup technologies etc.)
    • +
+

Common public considerations

+

The thing most consistent across public blockchain technologies, is that the technical decisions are +backed by token economics.

+

Put simply, creating a system where it's more financially rewarding to behave honestly, than it +is to subvert and cheat the system.

+

This means that participation costs, and that the mechanisms needed to reliably get your transactions +into these systems are complex. Also that the time it might take to get a transaction onto the chain +can be much longer than for a permissioned blockchain, with the potential to have to make a number +of adjustments/resubmissions.

+

The choice of whether to run your own node, or use a managed API, to access these blockchain ecosystems +is also a factor in the behavior of the transaction submission and event streaming.

+

FireFly architecture for public chains

+

One of the fastest evolving aspects of the Hyperledger FireFly ecosystem, is how it facilitates +enterprises to participate in these.

+

FireFly Public Transaction Architecture

+

The architecture is summarized as follows:

+
    +
  • New FireFly Transaction Manager runtime
    • +
  • Operates as a microservice extension of the FireFly Core
    • +
  • Uses the operation resource within FireFly Core to store and update state
    • +
  • Runs as a singleton and is responsible for nonce assignment
    • +
  • Takes as much heavy lifting away from blockchain specific connectors as possible
    • +
  • Lightweight FireFly Connector API (ffcapi)
    • +
  • Simple synchronous RPC operations that map to the most common operations supported across public blockchain technologies
    • +
  • Examples:
      +
    • Find the next nonce for a given signing key
      • +
    • Serialize a transaction from a set of JSON inputs and an interface definition
      • +
    • Submit an un-signed transaction with a given gas price to the blockchain, via a signing wallet
      • +
    • Establish a new block listener
      • +
    • Poll for new blocks
      • +
    • Establish a new event log listener
      • +
    • Poll for new events
      • +
    +
    • +
  • Pluggable Policy Engine
    • +
  • Invoked to make decisions on transaction submission
    • +
  • Responsible for gas price calculation
    • +
  • Able to intervene and adjust the characteristics of signing/submission
    • +
  • OSS reference implementation provided with Gas Station REST API integration
    • +
  • Confirmation Manager
    • +
  • Extracted from the Ethconnect codebase
    • +
  • Coupled to both transaction submission and event confirmation
    • +
  • Embeds an efficient block cache
    • +
  • Event Streams
    • +
  • Extracted from the Ethconnect codebase
    • +
  • Checkpoint restart based reliable at-least-once delivery of events
    • +
  • WebSockets interface upstream to FireFly Core
    • +
+

This evolution involves a significant refactoring of components used for production solutions in the FireFly Ethconnect +microservice since mid 2018. This was summarized in firefly-ethconnect#149, +and cumulated in the creation of a new repository in 2022.

+

You can follow the progress and contribute in this repo: https://github.com/hyperledger/firefly-transaction-manager

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/supernode_concept/index.html b/v1.3.1/overview/supernode_concept/index.html new file mode 100644 index 000000000..f88b58ef1 --- /dev/null +++ b/v1.3.1/overview/supernode_concept/index.html @@ -0,0 +1,3505 @@ + + + + + + + + + + + + + + + + + + + + + + + Introduction - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Introduction to Hyperledger FireFly

+

Your Gateway to Web3 Technologies

+

Hyperledger FireFly features

+

Hyperledger FireFly is an organization's gateway to Web3, including all the blockchain ecosystems that they participate in.

+

Multiple blockchains, multiple token economies, and multiple business networks.

+

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:

+
    +
  • Public Blockchains, Layer 2 scaling solutions, Side chains, and App chains
    • +
  • Permissioned Blockchains and Distributed Ledger Technologies (DLTs)
    • +
  • Decentralized storage solutions
    • +
  • Token ecosystems and standards
    • +
  • Smart Contracts, DeFi solutions and DAOs
    • +
  • Private off-chain encrypted communication rails
    • +
  • Advanced cryptography solutions
    • +
  • Identity frameworks
    • +
+

An Open Source Supernode for Web3 Apps

+

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.

+

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.

+

We call this a Supernode - it sits between the application and the underlying infrastructure nodes, +providing layers of additional function.

+

Without FireFly / with FireFly

+

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.

+

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.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/overview/usage_patterns/index.html b/v1.3.1/overview/usage_patterns/index.html new file mode 100644 index 000000000..c076f1bb3 --- /dev/null +++ b/v1.3.1/overview/usage_patterns/index.html @@ -0,0 +1,3508 @@ + + + + + + + + + + + + + + + + + + + + + + + Usage Patterns - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Usage Patterns

+ +

There are two modes of usage for Hyperledger Firefly: Web3 Gateway and Multiparty

+
+

A single runtime can operate in both of these modes, using different namespaces.

+
+

Web3 Gateway Mode

+

Gateway Mode

+

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.

+

In this mode you can:

+
    +
  • Transfer tokenized value
    • +
  • Invoke any other type of smart contract
    • +
  • Index data from the blockchain
    • +
  • Reliably trigger events in your applications and back-office core systems
    • +
  • Manage decentralized data (NFTs etc.)
    • +
  • Use a private address book to manage signing identities and relationships
    • +
  • ... and much more
    • +
+

Learn more about Web3 Gateway Mode.

+

Multiparty Mode

+

Multiparty mode is used to build multi-party systems, with a common application runtime deployed by each enterprise participant.

+

Multiparty Mode

+

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.

+

In this mode you can do everything you could do in Web3 Gateway mode, plus:

+
    +
  • Share and enforce common data formats
    • +
  • Exchange data privately, via an encrypted data bus
    • +
  • Structured JSON data payloads
    • +
  • Large documents
    • +
  • Coordinate on-chain and off-chain data exchange
    • +
  • Private data
    • +
  • Broadcast data
    • +
  • Mask on-chain activities using hashes
    • +
  • Use a shared address book to manage signing identities and relationships
    • +
  • ... and much more
    • +
+

Learn more about Multiparty Mode.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/api_post_syntax/index.html b/v1.3.1/reference/api_post_syntax/index.html new file mode 100644 index 000000000..6a1f22534 --- /dev/null +++ b/v1.3.1/reference/api_post_syntax/index.html @@ -0,0 +1,3479 @@ + + + + + + + + + + + + + + + + + + + + + + + API POST Syntax - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

API POST Syntax

+ +

Syntax Overview

+

Endpoints that allow submitting a transaction allow an optional query parameter called confirm. When confirm=true 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.

+

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.

+
+

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.

+
+

Example API Call

+

POST /api/v1/messages/broadcast?confirm=true

+

This will broadcast a message and wait for the message to be confirmed before returning.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/api_query_syntax/index.html b/v1.3.1/reference/api_query_syntax/index.html new file mode 100644 index 000000000..b9f8a6455 --- /dev/null +++ b/v1.3.1/reference/api_query_syntax/index.html @@ -0,0 +1,3738 @@ + + + + + + + + + + + + + + + + + + + + + + + API Query Syntax - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

API Query Syntax

+ +

Syntax Overview

+

REST collections provide filter, skip, limit and sort support.

+
    +
  • The field in the message is used as the query parameter
    • +
  • Syntax: field=[modifiers][operator]match-string
    • +
  • When multiple query parameters are supplied these are combined with AND
    • +
  • When the same query parameter is supplied multiple times, these are combined with OR
    • +
+

Example API Call

+

GET /api/v1/messages?confirmed=>0&type=broadcast&topic=t1&topic=t2&context=@someprefix&sort=sequence&descending&skip=100&limit=50

+

This states:

+
    +
  • Filter on confirmed greater than 0
    • +
  • Filter on type exactly equal to broadcast
    • +
  • Filter on topic exactly equal to t1 or t2
    • +
  • Filter on context containing the case-sensitive string someprefix
    • +
  • Sort on sequence in descending order
    • +
  • Paginate with limit of 50 and skip of 100 (e.g. get page 3, with 50/page)
    • +
+

Table of filter operations, which must be the first character of the query string (after the = in the above URL path example)

+

Operators

+

Operators are a type of comparison operation to +perform against the match string.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OperatorDescription
=Equal
(none)Equal (shortcut)
@Containing
^Starts with
$Ends with
<<Less than
<Less than (shortcut)
<=Less than or equal
>>Greater than
>Greater than (shortcut)
>=Greater than or equal
+
+

Shortcuts are only safe to use when your match +string starts with a-z, A-Z, 0-9, - or _.

+
+

Modifiers

+

Modifiers can appear before the operator, to change its +behavior.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ModifierDescription
!Not - negates the match
:Case insensitive
?Treat empty match string as null
[Combine using AND on the same field
]Combine using OR on the same field (default)
+

Detailed examples

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ExampleDescription
catEquals "cat"
=catEquals "cat" (same)
!=catNot equal to "cat"
:=catEqual to "CAT", "cat", "CaT etc.
!:catNot equal to "CAT", "cat", "CaT etc.
=!catEqual to "!cat" (! is after operator)
^cats/Starts with "cats/"
$_catEnds with with "_cat"
!:^cats/Does not start with "cats/", "CATs/" etc.
!$-catDoes not end with "-cat"
?=Is null
!?=Is not null
+

Time range example

+

For this case we need to combine multiple queries on the same created +field using AND semantics (with the [) modifier:

+
?created=[>>2021-01-01T00:00:00Z&created=[<=2021-01-02T00:00:00Z
+
+

So this means:

+
    +
  • created greater than 2021-01-01T00:00:00Z
    • +
  • AND
    • +
  • created less than or equal to 2021-01-02T00:00:00Z
    • +
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/blockchain_operation_errors/index.html b/v1.3.1/reference/blockchain_operation_errors/index.html new file mode 100644 index 000000000..1af6b0cd2 --- /dev/null +++ b/v1.3.1/reference/blockchain_operation_errors/index.html @@ -0,0 +1,3623 @@ + + + + + + + + + + + + + + + + + + + + + + + Blockchain Operation Errors - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Blockchain Operation Errors

+ +

Blockchain Error Messages

+

The receipt for a FireFly blockchain operation contains an extraInfo section that records additional information about the transaction. For example:

+
"receipt": {
+  ...
+  "extraInfo": [
+    {
+      {
+        "contractAddress":"0x87ae94ab290932c4e6269648bb47c86978af4436",
+        "cumulativeGasUsed":"33812",
+        "from":"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae",
+        "to":"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3",
+        "gasUsed":"33812",
+        "status":"0",
+        "errorMessage":"Not enough tokens", 
+      }
+    }
+  ],
+  ...
+},
+
+

The errorMessage 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 errorMessage 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.

+

Default Error Format With Hyperledger FireFly 1.3 and Hyperledger Besu 24.3.0

+

If FireFly is configured to connect to a Besu EVM client, and Besu has been configured with the revert-reason-enabled=true setting (note - the default value for Besu is false) error messages passed to FireFly from the blockchain client itself will be set correctly in the FireFly blockchain operation. For example:

+
    +
  • "errorMessage":"Not enough tokens" for a revert error string from a smart contract
    • +
+

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:

+
    +
  • "errorMessage":"FF23053: Error return value for custom error: <revert hex string>
    • +
  • "returnValue":"<revert hex string>"
    • +
+

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.

+

If FireFly is configured to connect to Besu without revert-reason-enabled=true the error message will be set to:

+
    +
  • "errorMessage":"FF23054: Error return value unavailable"
    • +
+

Error Retrieval Details

+

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 firefly-evmconnect blockchain connector.

+

Format of a firefly-evmconnect Error Message

+

The following section describes the way that the firefly-evmconnect plugin uses the errorMessage 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.

+

The errorMessage field for a firefly-evmconnect transaction may contain one of the following:

+
    +
  1. An error message from the FireFly blockchain connector
    2. +
  2. For example "FF23054: Error return value unavailable"
    3. +
  3. A decoded error string from the blockchain transaction
    4. +
  4. For example Not enough tokens
    5. +
  5. This could be an error string from a smart contract e.g. require(requestedTokens <= allowance, "Not enough tokens");
    6. +
  6. An un-decoded byte string from the blockchain transaction
    7. +
  7. For example +
    FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010
+
    8. +
  8. This could be a custom error from a smart contract e.g. +
    error AllowanceTooSmall(uint256 requested, uint256 allowance);
+...
+revert AllowanceTooSmall({ requested: 100, allowance: 20 });
+
    9. +
  9. If an error reason cannot be decoded the returnValue of the extraInfo will be set to the raw byte string. For example: +
    "receipt": {
+  ...
+  "extraInfo": [
+     {
+       {
+         "contractAddress":"0x87ae94ab290932c4e6269648bb47c86978af4436",
+         "cumulativeGasUsed":"33812",
+         "from":"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae",
+         "to":"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3",
+         "gasUsed":"33812",
+         "status":"0",
+         "errorMessage":"FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010", 
+         "returnValue":"0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010"
+       }
+     }
+  ],
+  ...
+},
+
    10. +
+

Retrieving EVM Blockchain Transaction Errors

+

The ability of a blockchain connector such as firefly-evmconnect 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 REVERT op code, with a REASON 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™ provides the --revert-reason-enabled 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 REVERT REASON. 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.

+

The firefly-evmconnect blockchain connector attempts to obtain the reason for a transaction revert and include it in the extraInfo field. It uses the following mechanisms, in this order:

+
    +
  1. Checks if the blockchain transaction receipt contains the revert reason.
    2. +
  2. If the revert reason is not in the receipt, and the connector.traceTXForRevertReason configuration option is set to true, calls debug_traceTransaction to obtain a full trace of the transaction and extract the revert reason. By default, connector.traceTXForRevertReason is set to false to avoid submitting high-resource requests to the EVM client.
    3. +
+

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 Error(string) signature format and includes the decoded string in the errorMessage + - If the reason is not a standard Error(String) error, sets the errorMessage to FF23053: Error return value for custom error: <raw hex string> and includes the raw byte string in the returnValue field.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/blockchain_operation_status/index.html b/v1.3.1/reference/blockchain_operation_status/index.html new file mode 100644 index 000000000..58f21ee57 --- /dev/null +++ b/v1.3.1/reference/blockchain_operation_status/index.html @@ -0,0 +1,3910 @@ + + + + + + + + + + + + + + + + + + + + + + + Blockchain Operation Status - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Blockchain Operation Status

+

Blockchain Operations

+

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.

+

Blockchain Operation Status

+

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.

+

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:

+

Sub-status diagram

+

To access detailed information about a blockchain operation FireFly 1.2 introduced a new query parameter, fetchStatus, to the /transaction/{txid}/operation/{opid} 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 detail field.

+

Blockchain Operation Example

+
{
+  "id": "04a8b0c4-03c2-4935-85a1-87d17cddc20a",
+  "created": "2022-05-16T01:23:15Z",
+  "namespace": "ns1",
+  "tx": "99543134-769b-42a8-8be4-a5f8873f969d",
+  "type": "blockchain_invoke",
+  "status": "Succeeded",
+  "plugin": "ethereum",
+  "input": {
+    // Input used to initiate the blockchain operation
+  },
+  "output": {
+    // Minimal blockchain operation data necessary
+    // to resolve the FF transaction
+  },
+  "detail": {
+    // Full blockchain operation information, including sub-status
+    // transitions that took place for the operation to succeed.
+  }
+}
+
+

Detail Status Structure

+

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:

+
    +
  • history an ordered list of status changes that have taken place during processing of the transaction
    • +
  • 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.
    • +
+

The history 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 Received, moving to Tracking, and finally ending up as Confirmed. In order to move from Received to Tracking several actions were performed: AssignNonce, RetrieveGasPrice, and SubmitTransaction.

+

History Example

+
{
+    ...
+    "lastSubmit": "2023-01-27T17:11:41.222375469Z",
+    "nonce": "14",
+    "history": [
+        {
+            "subStatus": "Received",
+            "time": "2023-01-27T17:11:41.122965803Z",
+            "actions": [
+                {
+                    "action": "AssignNonce",
+                    "count": 1,
+                    "lastInfo": {
+                        "nonce": "14"
+                    },
+                    "lastOccurrence": "2023-01-27T17:11:41.122967219Z",
+                    "time": "2023-01-27T17:11:41.122967136Z"
+                },
+                {
+                    "action": "RetrieveGasPrice",
+                    "count": 1,
+                    "lastInfo": {
+                        "gasPrice": "0"
+                    },
+                    "lastOccurrence": "2023-01-27T17:11:41.161213303Z",
+                    "time": "2023-01-27T17:11:41.161213094Z"
+                },
+                {
+                    "action": "SubmitTransaction",
+                    "count": 1,
+                    "lastInfo": {
+                        "txHash": "0x4c37de1cf320a1d5c949082bbec8ad5fe918e6621cec3948d609ec3f7deac243"
+                    },
+                    "lastOccurrence": "2023-01-27T17:11:41.222374636Z",
+                    "time": "2023-01-27T17:11:41.222374553Z"
+                }
+            ],
+        },
+        {
+            "subStatus": "Tracking",
+            "time": "2023-01-27T17:11:41.222400219Z",
+            "actions": [
+                {
+                    "action": "ReceiveReceipt",
+                    "count": 2,
+                    "lastInfo": {
+                        "protocolId": "000001265122/000000"
+                    },
+                    "lastOccurrence": "2023-01-27T17:11:57.93120838Z",
+                    "time": "2023-01-27T17:11:47.930332625Z"
+                },
+                {
+                    "action": "Confirm",
+                    "count": 1,
+                    "lastOccurrence": "2023-01-27T17:12:02.660275549Z",
+                    "time": "2023-01-27T17:12:02.660275382Z"
+                }
+            ],
+        },
+        {
+            "subStatus": "Confirmed",
+            "time": "2023-01-27T17:12:02.660309382Z",
+            "actions": [],
+        }
+    ]
+    ...
+}
+
+

Because the history 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 assignNonce might only happen once when the transaction is first processed by the connector. The historySummary field ensures that a minimal set of information is kept about every single subStatus type and action that has been recorded.

+

History Summary Example

+
{
+    ...
+    "historySummary": [
+        {
+            "count": 1,
+            "firstOccurrence": "2023-01-27T17:11:41.122966136Z",
+            "lastOccurrence": "2023-01-27T17:11:41.122966136Z",
+            "subStatus": "Received"
+        },
+        {
+            "count": 1,
+            "firstOccurrence": "2023-01-27T17:11:41.122967219Z",
+            "lastOccurrence": "2023-01-27T17:11:41.122967219Z",
+            "action": "AssignNonce"
+        },
+        {
+            "count": 1,
+            "firstOccurrence": "2023-01-27T17:11:41.161213303Z",
+            "lastOccurrence": "2023-01-27T17:11:41.161213303Z",
+            "action": "RetrieveGasPrice"
+        },
+        {
+            "count": 1,
+            "firstOccurrence": "2023-01-27T17:11:41.222374636Z",
+            "lastOccurrence": "2023-01-27T17:11:41.222374636Z",
+            "action": "SubmitTransaction"
+        },
+        {
+            "count": 1,
+            "firstOccurrence": "2023-01-27T17:11:41.222400678Z",
+            "lastOccurrence": "",
+            "subStatus": "Tracking"
+        },
+        {
+            "count": 1,
+            "firstOccurrence": "2023-01-27T17:11:57.93120838Z",
+            "lastOccurrence": "2023-01-27T17:11:57.93120838Z",
+            "action": "ReceiveReceipt"
+        },
+        {
+            "count": 1,
+            "firstOccurrence": "2023-01-27T17:12:02.660309382Z",
+            "lastOccurrence": "2023-01-27T17:12:02.660309382Z",
+            "action": "Confirm"
+        },
+        {
+            "count": 1,
+            "firstOccurrence": "2023-01-27T17:12:02.660309757Z",
+            "lastOccurrence": "2023-01-27T17:12:02.660309757Z",
+            "subStatus": "Confirmed"
+        }
+    ]
+}
+
+

Public Chain Operations

+

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 history for a public blockchain operation might include a large number of subStatus entries. Using the example sub-status values above, a blockchain operation might move from Tracking to Stale, back to Tracking, back to Stale and so on.

+

Below is an example of the history for a public blockchain operation.

+

Polygon Example

+
{
+    ...
+    "lastSubmit": "2023-01-27T17:11:41.222375469Z",
+    "nonce": "14",
+    "history": [
+        {
+            "subStatus": "Received",
+            "time": "2023-01-27T17:11:41.122965803Z",
+            "actions": [
+                {
+                    "action": "AssignNonce",
+                    "count": 1,
+                    "lastInfo": {
+                        "nonce": "1"
+                    },
+                    "lastOccurrence": "2023-01-27T17:11:41.122967219Z",
+                    "time": "2023-01-27T17:11:41.122967136Z"
+                },
+                {
+                    "action": "RetrieveGasPrice",
+                    "count": 1,
+                    "lastInfo": {
+                        "gasPrice": "34422243"
+                    },
+                    "lastOccurrence": "2023-01-27T17:11:41.161213303Z",
+                    "time": "2023-01-27T17:11:41.161213094Z"
+                },
+                {
+                    "action": "SubmitTransaction",
+                    "count": 1,
+                    "lastInfo": {
+                        "txHash": "0x83ba5e1cf320a1d5c949082bbec8ae7fe918e6621cec39478609ec3f7deacbdb"
+                    },
+                    "lastOccurrence": "2023-01-27T17:11:41.222374636Z",
+                    "time": "2023-01-27T17:11:41.222374553Z"
+                }
+            ],
+        },
+        {
+            "subStatus": "Tracking",
+            "time": "2023-01-27T17:11:41.222400219Z",
+            "actions": [],
+        },
+        {
+            "subStatus": "Stale",
+            "time": "2023-01-27T17:13:21.222100434Z",
+            "actions": [
+                {
+                    "action": "RetrieveGasPrice",
+                    "count": 1,
+                    "lastInfo": {
+                        "gasPrice": "44436243"
+                    },
+                    "lastOccurrence": "2023-01-27T17:13:22.93120838Z",
+                    "time": "2023-01-27T17:13:22.93120838Z"
+                },
+                {
+                    "action": "SubmitTransaction",
+                    "count": 1,
+                    "lastInfo": {
+                        "txHash": "0x7b3a5e1ccbc0a1d5c949082bbec8ae7fe918e6621cec39478609ec7aea6103d5"
+                    },
+                    "lastOccurrence": "2023-01-27T17:13:32.656374637Z",
+                    "time": "2023-01-27T17:13:32.656374637Z"
+                }
+            ],
+        },
+        {
+            "subStatus": "Tracking",
+            "time": "2023-01-27T17:13:33.434400219Z",
+            "actions": [],
+        },
+        {
+            "subStatus": "Stale",
+            "time": "2023-01-27T17:15:21.222100434Z",
+            "actions": [
+                {
+                    "action": "RetrieveGasPrice",
+                    "count": 1,
+                    "lastInfo": {
+                        "gasPrice": "52129243"
+                    },
+                    "lastOccurrence": "2023-01-27T17:15:22.93120838Z",
+                    "time": "2023-01-27T17:15:22.93120838Z"
+                },
+                {
+                    "action": "SubmitTransaction",
+                    "count": 1,
+                    "lastInfo": {
+                        "txHash": "0x89995e1ccbc0a1d5c949082bbec8ae7fe918e6621cec39478609ec7a8c64abc"
+                    },
+                    "lastOccurrence": "2023-01-27T17:15:32.656374637Z",
+                    "time": "2023-01-27T17:15:32.656374637Z"
+                }
+            ],
+        },
+        {
+            "subStatus": "Tracking",
+            "time": "2023-01-27T17:15:33.434400219Z",
+            "actions": [
+                {
+                    "action": "ReceiveReceipt",
+                    "count": 1,
+                    "lastInfo": {
+                        "protocolId": "000004897621/000000"
+                    },
+                    "lastOccurrence": "2023-01-27T17:15:33.94120833Z",
+                    "time": "2023-01-27T17:15:33.94120833Z"
+                },
+                {
+                    "action": "Confirm",
+                    "count": 1,
+                    "lastOccurrence": "2023-01-27T17:16:02.780275549Z",
+                    "time": "2023-01-27T17:16:02.780275382Z"
+                }
+            ],
+        },
+        {
+            "subStatus": "Confirmed",
+            "time": "2023-01-27T17:16:03.990309381Z",
+            "actions": [],
+        }
+    ]
+    ...
+}
+
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/config/index.html b/v1.3.1/reference/config/index.html new file mode 100644 index 000000000..52d0ec23e --- /dev/null +++ b/v1.3.1/reference/config/index.html @@ -0,0 +1,12001 @@ + + + + + + + + + + + + + + + + + + + + + + + Configuration Reference - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Configuration Reference

+ +

admin

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
enabledDeprecated - use spi.enabled insteadboolean<nil>
+

api

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
defaultFilterLimitThe maximum number of rows to return if no limit is specified on an API requestint25
dynamicPublicURLHeaderDynamic header that informs the backend the base public URL for the request, in order to build URL links in OpenAPI/SwaggerUIstring<nil>
maxFilterLimitThe largest value of limit that an HTTP client can specify in a requestint1000
passthroughHeadersA list of HTTP request headers to pass through to dependency microservices[]string[]
requestMaxTimeoutThe maximum amount of time that an HTTP client can specify in a Request-Timeout header to keep a specific request opentime.Duration10m
requestTimeoutThe maximum amount of time that a request is allowed to remain opentime.Duration120s
+

asset.manager

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
keyNormalizationMechanism to normalize keys before using them. Valid options are blockchain_plugin - use blockchain plugin (default) or none - do not attempt normalization (deprecated - use namespaces.predefined[].asset.manager.keyNormalization)stringblockchain_plugin
+

batch.manager

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
minimumPollDelayThe minimum time the batch manager waits between polls on the DB - to prevent thrashingtime.Duration100ms
pollTimeoutHow long to wait without any notifications of new messages before doing a page querytime.Duration30s
readPageSizeThe size of each page of messages read from the database into memory when assembling batchesint100
+

batch.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
factorThe retry backoff factorfloat322
initDelayThe initial retry delaytime.Duration250ms
maxDelayThe maximum retry delaytime.Duration30s
+

blobreceiver.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
factorThe retry backoff factorfloat322
initialDelayThe initial retry delaytime.Duration250ms
maxDelayThe maximum retry delaytime.Duration1m
+

blobreceiver.worker

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
batchMaxInsertsThe maximum number of items the blob receiver worker will insert in a batchint200
batchTimeoutThe maximum amount of the the blob receiver worker will waittime.Duration50ms
countThe number of blob receiver workersint5
+

broadcast.batch

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
agentTimeoutHow long to keep around a batching agent for a sending identity before disposalstring2m
payloadLimitThe maximum payload size of a batch for broadcast messagesBytesSize800Kb
sizeThe maximum number of messages that can be packed into a batchint200
timeoutThe timeout to wait for a batch to fill, before sendingtime.Duration1s
+

cache

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
enabledEnables caching, defaults to truebooleantrue
+

cache.addressresolver

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
limitMax number of cached items for address resolverint1000
ttlTime to live of cached items for address resolverstring24h
+

cache.batch

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
limitMax number of cached items for batchesint100
ttlTime to live of cache items for batchesstring5m
+

cache.blockchain

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
limitMax number of cached items for blockchainint100
ttlTime to live of cached items for blockchainstring5m
+

cache.blockchainevent

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
limitMax number of cached blockchain events for transactionsint1000
ttlTime to live of cached blockchain events for transactionsstring5m
+

cache.eventlistenertopic

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
limitMax number of cached items for blockchain listener topicsint100
ttlTime to live of cached items for blockchain listener topicsstring5m
+

cache.group

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
limitMax number of cached items for groupsint50
ttlTime to live of cached items for groupsstring1h
+

cache.identity

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
limitMax number of cached identities for identity managerint100
ttlTime to live of cached identities for identity managerstring1h
+

cache.message

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
sizeMax size of cached messages for data managerBytesSize50Mb
ttlTime to live of cached messages for data managerstring5m
+

cache.methods

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
limitMax number of cached items for schema validations on blockchain methodsint200
ttlTime to live of cached items for schema validations on blockchain methodsstring5m
+

cache.operations

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
limitMax number of cached items for operationsint1000
ttlTime to live of cached items for operationsstring5m
+

cache.tokenpool

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
limitMax number of cached items for token poolsint100
ttlTime to live of cached items for token poolstring1h
+

cache.transaction

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
sizeMax size of cached transactionsBytesSize1Mb
ttlTime to live of cached transactionsstring5m
+

cache.validator

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
sizeMax size of cached validators for data managerBytesSize1Mb
ttlTime to live of cached validators for data managerstring1h
+

config

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
autoReloadMonitor the configuration file for changes, and automatically add/remove/reload namespaces and pluginsboolean<nil>
+

cors

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
credentialsCORS setting to control whether a browser allows credentials to be sent to this APIbooleantrue
debugWhether debug is enabled for the CORS implementationbooleanfalse
enabledWhether CORS is enabledbooleantrue
headersCORS setting to control the allowed headers[]string[*]
maxAgeThe maximum age a browser should rely on CORS checkstime.Duration600
methodsCORS setting to control the allowed methods[]string[GET POST PUT PATCH DELETE]
originsCORS setting to control the allowed origins[]string[*]
+

debug

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
addressThe HTTP interface the go debugger binds tostringlocalhost
portAn HTTP port on which to enable the go debuggerint-1
+

download.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
factorThe retry backoff factorfloat322
initialDelayThe initial retry delaytime.Duration100ms
maxAttemptsThe maximum number attemptsint100
maxDelayThe maximum retry delaytime.Duration1m
+

download.worker

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
countThe number of download workersint10
queueLengthThe length of the work queue in the channel to the workers - defaults to 2x the worker countint<nil>
+

event.aggregator

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
batchSizeThe maximum number of records to read from the DB before performing an aggregation runBytesSize200
batchTimeoutHow long to wait for new events to arrive before performing aggregation on a page of eventstime.Duration0ms
firstEventThe first event the aggregator should process, if no previous offest is stored in the DB. Valid options are oldest or neweststringoldest
pollTimeoutThe time to wait without a notification of new events, before trying a select on the tabletime.Duration30s
rewindQueryLimitSafety limit on the maximum number of records to search when performing queries to search for rewindsint1000
rewindQueueLengthThe size of the queue into the rewind dispatcherint10
rewindTimeoutThe minimum time to wait for rewinds to accumulate before resolving themtime.Duration50ms
+

event.aggregator.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
factorThe retry backoff factorfloat322
initDelayThe initial retry delaytime.Duration100ms
maxDelayThe maximum retry delaytime.Duration30s
+

event.dbevents

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
bufferSizeThe size of the buffer of change eventsBytesSize100
+

event.dispatcher

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
batchTimeoutA short time to wait for new events to arrive before re-polling for new eventstime.Duration0ms
bufferLengthThe number of events + attachments an individual dispatcher should hold in memory ready for delivery to the subscriptionint5
pollTimeoutThe time to wait without a notification of new events, before trying a select on the tabletime.Duration30s
+

event.dispatcher.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
factorThe retry backoff factorfloat32<nil>
initDelayThe initial retry delaytime.Duration<nil>
maxDelayThe maximum retry delaytime.Duration<nil>
+

event.transports

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
defaultThe default event transport for new subscriptionsstringwebsockets
enabledWhich event interface plugins are enabledboolean[websockets webhooks]
+

events.webhooks

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
connectionTimeoutThe maximum amount of time that a connection is allowed to remain with no data transmittedtime.Duration30s
expectContinueTimeoutSee ExpectContinueTimeout in the Go docstime.Duration1s
headersAdds custom headers to HTTP requestsmap[string]string<nil>
idleTimeoutThe max duration to hold a HTTP keepalive connection between callstime.Duration475ms
maxConnsPerHostThe max number of connections, per unique hostname. Zero means no limitint0
maxIdleConnsThe max number of idle connections to hold pooledint100
passthroughHeadersEnabledEnable passing through the set of allowed HTTP request headersbooleanfalse
requestTimeoutThe maximum amount of time that a request is allowed to remain opentime.Duration30s
tlsHandshakeTimeoutThe maximum amount of time to wait for a successful TLS handshaketime.Duration10s
+

events.webhooks.auth

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordPasswordstring<nil>
usernameUsernamestring<nil>
+

events.webhooks.proxy

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
urlOptional HTTP proxy server to connect throughstring<nil>
+

events.webhooks.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
countThe maximum number of times to retryint5
enabledEnables retriesbooleanfalse
errorStatusCodeRegexThe regex that the error response status code must match to trigger retrystring<nil>
initWaitTimeThe initial retry delaytime.Duration250ms
maxWaitTimeThe maximum retry delaytime.Duration30s
+

events.webhooks.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

events.websockets

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
readBufferSizeWebSocket read buffer sizeBytesSize16Kb
writeBufferSizeWebSocket write buffer sizeBytesSize16Kb
+

histograms

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
maxChartRowsThe maximum rows to fetch for each histogram bucketint100
+

http

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
addressThe IP address on which the HTTP API should listenIP Address string127.0.0.1
portThe port on which the HTTP API should listenint5000
publicURLThe fully qualified public URL for the API. This is used for building URLs in HTTP responses and in OpenAPI Spec generationURL string<nil>
readTimeoutThe maximum time to wait when reading from an HTTP connectiontime.Duration15s
shutdownTimeoutThe maximum amount of time to wait for any open HTTP requests to finish before shutting down the HTTP servertime.Duration10s
writeTimeoutThe maximum time to wait when writing to an HTTP connectiontime.Duration15s
+

http.auth

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
typeThe auth plugin to use for server side authentication of requestsstring<nil>
+

http.auth.basic

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordfileThe path to a .htpasswd file to use for authenticating requests. Passwords should be hashed with bcrypt.string<nil>
+

http.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

log

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
compressDetermines if the rotated log files should be compressed using gzipboolean<nil>
filenameFilename is the file to write logs to. Backup log files will be retained in the same directorystring<nil>
filesizeMaxSize is the maximum size the log file before it gets rotatedBytesSize100m
forceColorForce color to be enabled, even when a non-TTY output is detectedboolean<nil>
includeCodeInfoEnables 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.booleanfalse
levelThe log level - error, warn, info, debug, tracestringinfo
maxAgeThe maximum time to retain old log files based on the timestamp encoded in their filenametime.Duration24h
maxBackupsMaximum number of old log files to retainint2
noColorForce color to be disabled, event when TTY output is detectedboolean<nil>
timeFormatCustom time format for logsTime format string2006-01-02T15:04:05.000Z07:00
utcUse UTC timestamps for logsbooleanfalse
+

log.json

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
enabledEnables JSON formatted logs rather than text. All log color settings are ignored when enabled.booleanfalse
+

log.json.fields

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
fileconfigures the JSON key containing the calling filestringfile
funcConfigures the JSON key containing the calling functionstringfunc
levelConfigures the JSON key containing the log levelstringlevel
messageConfigures the JSON key containing the log messagestringmessage
timestampConfigures the JSON key containing the timestamp of the logstring@timestamp
+

message.writer

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
batchMaxInsertsThe maximum number of database inserts to include when writing a single batch of messages + dataint200
batchTimeoutHow long to wait for more messages to arrive before flushing the batchtime.Duration10ms
countThe number of message writer workersint5
+

metrics

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
addressThe IP address on which the metrics HTTP API should listenint127.0.0.1
enabledEnables the metrics APIbooleantrue
pathThe path from which to serve the Prometheus metricsstring/metrics
portThe port on which the metrics HTTP API should listenint6000
publicURLThe fully qualified public URL for the metrics API. This is used for building URLs in HTTP responses and in OpenAPI Spec generationURL string<nil>
readTimeoutThe maximum time to wait when reading from an HTTP connectiontime.Duration15s
shutdownTimeoutThe maximum amount of time to wait for any open HTTP requests to finish before shutting down the HTTP servertime.Duration10s
writeTimeoutThe maximum time to wait when writing to an HTTP connectiontime.Duration15s
+

metrics.auth

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
typeThe auth plugin to use for server side authentication of requestsstring<nil>
+

metrics.auth.basic

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordfileThe path to a .htpasswd file to use for authenticating requests. Passwords should be hashed with bcrypt.string<nil>
+

metrics.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

namespaces

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
defaultThe default namespace - must be in the predefined liststringdefault
predefinedA list of namespaces to ensure exists, without requiring a broadcast from the networkList string<nil>
+

namespaces.predefined[]

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
defaultKeyA default signing key for blockchain transactions within this namespacestring<nil>
descriptionA description for the namespacestring<nil>
nameThe name of the namespace (must be unique)string<nil>
pluginsThe list of plugins for this namespacestring<nil>
+

namespaces.predefined[].asset.manager

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
keyNormalizationMechanism to normalize keys before using them. Valid options are blockchain_plugin - use blockchain plugin (default) or none - do not attempt normalizationstring<nil>
+

namespaces.predefined[].multiparty

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
enabledEnables multi-party mode for this namespace (defaults to true if an org name or key is configured, either here or at the root level)boolean<nil>
networknamespaceThe shared namespace name to be sent in multiparty messages, if it differs from the local namespace namestring<nil>
+

namespaces.predefined[].multiparty.contract[]

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
firstEventThe first event the contract should process. Valid options are oldest or neweststring<nil>
locationA blockchain-specific contract location. For example, an Ethereum contract address, or a Fabric chaincode name and channelstring<nil>
optionsBlockchain-specific contract optionsstring<nil>
+

namespaces.predefined[].multiparty.node

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
descriptionA description for the node in this namespacestring<nil>
nameThe node name for this namespacestring<nil>
+

namespaces.predefined[].multiparty.org

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
descriptionA description for the local root organization within this namespacestring<nil>
keyThe signing key allocated to the root organization within this namespacestring<nil>
nameA short name for the local root organization within this namespacestring<nil>
+

namespaces.predefined[].tlsConfigs[]

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
nameName of the TLS Configstring<nil>
+

namespaces.predefined[].tlsConfigs[].tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

namespaces.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
factorThe retry backoff factorfloat322
initDelayThe initial retry delaytime.Duration5s
maxDelayThe maximum retry delaytime.Duration1m
+

node

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
descriptionThe description of this FireFly nodestring<nil>
nameThe name of this FireFly nodestring<nil>
+

opupdate.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
factorThe retry backoff factorfloat322
initialDelayThe initial retry delaytime.Duration250ms
maxDelayThe maximum retry delaytime.Duration1m
+

opupdate.worker

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
batchMaxInsertsThe maximum number of database inserts to include when writing a single batch of messages + dataint200
batchTimeoutHow long to wait for more messages to arrive before flushing the batchtime.Duration50ms
countThe number of operation update worksint5
queueLengthThe size of the queue for the Operation Update workerint50
+

orchestrator

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
startupAttemptsThe number of times to attempt to connect to core infrastructure on startupstring5
+

org

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
descriptionA description of the organization to which this FireFly node belongs (deprecated - should be set on each multi-party namespace instead)string<nil>
keyThe signing key allocated to the organization (deprecated - should be set on each multi-party namespace instead)string<nil>
nameThe name of the organization to which this FireFly node belongs (deprecated - should be set on each multi-party namespace instead)string<nil>
+

plugins

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
authAuthorization plugin configurationmap[string]string<nil>
blockchainThe list of configured Blockchain pluginsstring<nil>
databaseThe list of configured Database pluginsstring<nil>
dataexchangeThe array of configured Data Exchange pluginsstring<nil>
identityThe list of available Identity pluginsstring<nil>
sharedstorageThe list of configured Shared Storage pluginsstring<nil>
tokensThe token plugin configurationsstring<nil>
+

plugins.auth[]

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
nameThe name of the auth plugin to usestring<nil>
typeThe type of the auth plugin to usestring<nil>
+

plugins.auth[].basic

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordfileThe path to a .htpasswd file to use for authenticating requests. Passwords should be hashed with bcrypt.string<nil>
+

plugins.blockchain[]

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
nameThe name of the configured Blockchain pluginstring<nil>
typeThe type of the configured Blockchain Connector pluginstring<nil>
+

plugins.blockchain[].ethereum.addressResolver

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
alwaysResolveCauses 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 cachingboolean<nil>
bodyTemplateThe body go template string to use when making HTTP requests. The template input contains '.Key' and '.Intent' string variables.Go Template string<nil>
connectionTimeoutThe maximum amount of time that a connection is allowed to remain with no data transmittedtime.Duration30s
expectContinueTimeoutSee ExpectContinueTimeout in the Go docstime.Duration1s
headersAdds custom headers to HTTP requestsstring<nil>
idleTimeoutThe max duration to hold a HTTP keepalive connection between callstime.Duration475ms
maxConnsPerHostThe max number of connections, per unique hostname. Zero means no limitint0
maxIdleConnsThe max number of idle connections to hold pooledint100
methodThe HTTP method to use when making requests to the Address ResolverstringGET
passthroughHeadersEnabledEnable passing through the set of allowed HTTP request headersbooleanfalse
requestTimeoutThe maximum amount of time that a request is allowed to remain opentime.Duration30s
responseFieldThe name of a JSON field that is provided in the response, that contains the ethereum address (default address)stringaddress
retainOriginalWhen true the original pre-resolved string is retained after the lookup, and passed down to Ethconnect as the from addressboolean<nil>
tlsHandshakeTimeoutThe maximum amount of time to wait for a successful TLS handshaketime.Duration10s
urlThe URL of the Address Resolverstring<nil>
urlTemplateThe URL Go template string to use when calling the Address Resolver. The template input contains '.Key' and '.Intent' string variables.Go Template string<nil>
+

plugins.blockchain[].ethereum.addressResolver.auth

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordPasswordstring<nil>
usernameUsernamestring<nil>
+

plugins.blockchain[].ethereum.addressResolver.proxy

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
urlOptional HTTP proxy server to use when connecting to the Address ResolverURL string<nil>
+

plugins.blockchain[].ethereum.addressResolver.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
countThe maximum number of times to retryint5
enabledEnables retriesbooleanfalse
errorStatusCodeRegexThe regex that the error response status code must match to trigger retrystring<nil>
initWaitTimeThe initial retry delaytime.Duration250ms
maxWaitTimeThe maximum retry delaytime.Duration30s
+

plugins.blockchain[].ethereum.addressResolver.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

plugins.blockchain[].ethereum.ethconnect

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
batchSizeThe number of events Ethconnect should batch together for delivery to FireFly core. Only applies when automatically creating a new event streamint50
batchTimeoutHow 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 streamtime.Duration500
connectionTimeoutThe maximum amount of time that a connection is allowed to remain with no data transmittedtime.Duration30s
expectContinueTimeoutSee ExpectContinueTimeout in the Go docstime.Duration1s
fromBlockThe first event this FireFly instance should listen to from the BatchPin smart contract. Default=0. Only affects initial creation of the event streamAddress string0
headersAdds custom headers to HTTP requestsmap[string]string<nil>
idleTimeoutThe max duration to hold a HTTP keepalive connection between callstime.Duration475ms
instanceThe Ethereum address of the FireFly BatchPin smart contract that has been deployed to the blockchainAddress string<nil>
maxConnsPerHostThe max number of connections, per unique hostname. Zero means no limitint0
maxIdleConnsThe max number of idle connections to hold pooledint100
passthroughHeadersEnabledEnable passing through the set of allowed HTTP request headersbooleanfalse
prefixLongThe prefix that will be used for Ethconnect specific HTTP headers when FireFly makes requests to Ethconnectstringfirefly
prefixShortThe prefix that will be used for Ethconnect specific query parameters when FireFly makes requests to Ethconnectstringfly
requestTimeoutThe maximum amount of time that a request is allowed to remain opentime.Duration30s
tlsHandshakeTimeoutThe maximum amount of time to wait for a successful TLS handshaketime.Duration10s
topicThe websocket listen topic that the node should register on, which is important if there are multiple nodes using a single ethconnectstring<nil>
urlThe URL of the Ethconnect instanceURL string<nil>
+

plugins.blockchain[].ethereum.ethconnect.auth

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordPasswordstring<nil>
usernameUsernamestring<nil>
+

plugins.blockchain[].ethereum.ethconnect.backgroundStart

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
enabledStart the Ethconnect plugin in the background and enter retry loop if failed to startboolean<nil>
factorSet the factor by which the delay increases when retryingfloat322
initialDelayDelay between restarts in the case where we retry to restart the ethereum plugintime.Duration5s
maxDelayMax delay between restarts in the case where we retry to restart the ethereum plugintime.Duration1m
+

plugins.blockchain[].ethereum.ethconnect.proxy

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
urlOptional HTTP proxy server to use when connecting to EthconnectURL string<nil>
+

plugins.blockchain[].ethereum.ethconnect.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
countThe maximum number of times to retryint5
enabledEnables retriesbooleanfalse
errorStatusCodeRegexThe regex that the error response status code must match to trigger retrystring<nil>
initWaitTimeThe initial retry delaytime.Duration250ms
maxWaitTimeThe maximum retry delaytime.Duration30s
+

plugins.blockchain[].ethereum.ethconnect.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

plugins.blockchain[].ethereum.ethconnect.ws

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
connectionTimeoutThe amount of time to wait while establishing a connection (or auto-reconnection)time.Duration45s
heartbeatIntervalThe amount of time to wait between heartbeat signals on the WebSocket connectiontime.Duration30s
initialConnectAttemptsThe number of attempts FireFly will make to connect to the WebSocket when starting up, before failingint5
pathThe WebSocket sever URL to which FireFly should connectWebSocket URL string<nil>
readBufferSizeThe size in bytes of the read buffer for the WebSocket connectionBytesSize16Kb
urlURL to use for WebSocket - overrides url one level up (in the HTTP config)string<nil>
writeBufferSizeThe size in bytes of the write buffer for the WebSocket connectionBytesSize16Kb
+

plugins.blockchain[].ethereum.fftm

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
connectionTimeoutThe maximum amount of time that a connection is allowed to remain with no data transmittedtime.Duration30s
expectContinueTimeoutSee ExpectContinueTimeout in the Go docstime.Duration1s
headersAdds custom headers to HTTP requestsmap[string]string<nil>
idleTimeoutThe max duration to hold a HTTP keepalive connection between callstime.Duration475ms
maxConnsPerHostThe max number of connections, per unique hostname. Zero means no limitint0
maxIdleConnsThe max number of idle connections to hold pooledint100
passthroughHeadersEnabledEnable passing through the set of allowed HTTP request headersbooleanfalse
requestTimeoutThe maximum amount of time that a request is allowed to remain opentime.Duration30s
tlsHandshakeTimeoutThe maximum amount of time to wait for a successful TLS handshaketime.Duration10s
urlThe URL of the FireFly Transaction Manager runtime, if enabledstring<nil>
+

plugins.blockchain[].ethereum.fftm.auth

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordPasswordstring<nil>
usernameUsernamestring<nil>
+

plugins.blockchain[].ethereum.fftm.proxy

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
urlOptional HTTP proxy server to use when connecting to the Transaction Managerstring<nil>
+

plugins.blockchain[].ethereum.fftm.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
countThe maximum number of times to retryint5
enabledEnables retriesbooleanfalse
errorStatusCodeRegexThe regex that the error response status code must match to trigger retrystring<nil>
initWaitTimeThe initial retry delaytime.Duration250ms
maxWaitTimeThe maximum retry delaytime.Duration30s
+

plugins.blockchain[].ethereum.fftm.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

plugins.blockchain[].fabric.fabconnect

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
batchSizeThe number of events Fabconnect should batch together for delivery to FireFly core. Only applies when automatically creating a new event streamint50
batchTimeoutThe maximum amount of time to wait for a batch to completetime.Duration500
chaincodeThe name of the Fabric chaincode that FireFly will use for BatchPin transactions (deprecated - use fireflyContract[].chaincode)string<nil>
channelThe Fabric channel that FireFly will use for BatchPin transactionsstring<nil>
connectionTimeoutThe maximum amount of time that a connection is allowed to remain with no data transmittedtime.Duration30s
expectContinueTimeoutSee ExpectContinueTimeout in the Go docstime.Duration1s
headersAdds custom headers to HTTP requestsmap[string]string<nil>
idleTimeoutThe max duration to hold a HTTP keepalive connection between callstime.Duration475ms
maxConnsPerHostThe max number of connections, per unique hostname. Zero means no limitint0
maxIdleConnsThe max number of idle connections to hold pooledint100
passthroughHeadersEnabledEnable passing through the set of allowed HTTP request headersbooleanfalse
prefixLongThe prefix that will be used for Fabconnect specific HTTP headers when FireFly makes requests to Fabconnectstringfirefly
prefixShortThe prefix that will be used for Fabconnect specific query parameters when FireFly makes requests to Fabconnectstringfly
requestTimeoutThe maximum amount of time that a request is allowed to remain opentime.Duration30s
signerThe Fabric signing key to use when submitting transactions to Fabconnectstring<nil>
tlsHandshakeTimeoutThe maximum amount of time to wait for a successful TLS handshaketime.Duration10s
topicThe websocket listen topic that the node should register on, which is important if there are multiple nodes using a single Fabconnectstring<nil>
urlThe URL of the Fabconnect instanceURL string<nil>
+

plugins.blockchain[].fabric.fabconnect.auth

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordPasswordstring<nil>
usernameUsernamestring<nil>
+

plugins.blockchain[].fabric.fabconnect.backgroundStart

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
enabledStart the fabric plugin in the background and enter retry loop if failed to startboolean<nil>
factorSet the factor by which the delay increases when retryingfloat322
initialDelayDelay between restarts in the case where we retry to restart the fabric plugintime.Duration5s
maxDelayMax delay between restarts in the case where we retry to restart the fabric plugintime.Duration1m
+

plugins.blockchain[].fabric.fabconnect.proxy

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
urlOptional HTTP proxy server to use when connecting to FabconnectURL string<nil>
+

plugins.blockchain[].fabric.fabconnect.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
countThe maximum number of times to retryint5
enabledEnables retriesbooleanfalse
errorStatusCodeRegexThe regex that the error response status code must match to trigger retrystring<nil>
initWaitTimeThe initial retry delaytime.Duration250ms
maxWaitTimeThe maximum retry delaytime.Duration30s
+

plugins.blockchain[].fabric.fabconnect.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

plugins.blockchain[].fabric.fabconnect.ws

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
connectionTimeoutThe amount of time to wait while establishing a connection (or auto-reconnection)time.Duration45s
heartbeatIntervalThe amount of time to wait between heartbeat signals on the WebSocket connectiontime.Duration30s
initialConnectAttemptsThe number of attempts FireFly will make to connect to the WebSocket when starting up, before failingint5
pathThe WebSocket sever URL to which FireFly should connectWebSocket URL string<nil>
readBufferSizeThe size in bytes of the read buffer for the WebSocket connectionBytesSize16Kb
urlURL to use for WebSocket - overrides url one level up (in the HTTP config)string<nil>
writeBufferSizeThe size in bytes of the write buffer for the WebSocket connectionBytesSize16Kb
+

plugins.blockchain[].tezos.addressResolver

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
alwaysResolveCauses the address resolver to be invoked on every API call that submits a signing key. Also disables any result cachingboolean<nil>
bodyTemplateThe body go template string to use when making HTTP requestsGo Template string<nil>
connectionTimeoutThe maximum amount of time that a connection is allowed to remain with no data transmittedtime.Duration30s
expectContinueTimeoutSee ExpectContinueTimeout in the Go docstime.Duration1s
headersAdds custom headers to HTTP requestsmap[string]string<nil>
idleTimeoutThe max duration to hold a HTTP keepalive connection between callstime.Duration475ms
maxConnsPerHostThe max number of connections, per unique hostname. Zero means no limitint0
maxIdleConnsThe max number of idle connections to hold pooledint100
methodThe HTTP method to use when making requests to the Address ResolverstringGET
passthroughHeadersEnabledEnable passing through the set of allowed HTTP request headersbooleanfalse
requestTimeoutThe maximum amount of time that a request is allowed to remain opentime.Duration30s
responseFieldThe name of a JSON field that is provided in the response, that contains the tezos address (default address)stringaddress
retainOriginalWhen true the original pre-resolved string is retained after the lookup, and passed down to Tezosconnect as the from addressboolean<nil>
tlsHandshakeTimeoutThe maximum amount of time to wait for a successful TLS handshaketime.Duration10s
urlThe URL of the Address Resolverstring<nil>
urlTemplateThe URL Go template string to use when calling the Address Resolver. The template input contains '.Key' and '.Intent' string variables.Go Template string<nil>
+

plugins.blockchain[].tezos.addressResolver.auth

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordPasswordstring<nil>
usernameUsernamestring<nil>
+

plugins.blockchain[].tezos.addressResolver.proxy

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
urlOptional HTTP proxy server to connect throughstring<nil>
+

plugins.blockchain[].tezos.addressResolver.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
countThe maximum number of times to retryint5
enabledEnables retriesbooleanfalse
errorStatusCodeRegexThe regex that the error response status code must match to trigger retrystring<nil>
initWaitTimeThe initial retry delaytime.Duration250ms
maxWaitTimeThe maximum retry delaytime.Duration30s
+

plugins.blockchain[].tezos.addressResolver.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

plugins.blockchain[].tezos.tezosconnect

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
batchSizeThe number of events Tezosconnect should batch together for delivery to FireFly core. Only applies when automatically creating a new event streamint50
batchTimeoutHow 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 streamtime.Duration500
connectionTimeoutThe maximum amount of time that a connection is allowed to remain with no data transmittedtime.Duration30s
expectContinueTimeoutSee ExpectContinueTimeout in the Go docstime.Duration1s
headersAdds custom headers to HTTP requestsmap[string]string<nil>
idleTimeoutThe max duration to hold a HTTP keepalive connection between callstime.Duration475ms
maxConnsPerHostThe max number of connections, per unique hostname. Zero means no limitint0
maxIdleConnsThe max number of idle connections to hold pooledint100
passthroughHeadersEnabledEnable passing through the set of allowed HTTP request headersbooleanfalse
prefixLongThe prefix that will be used for Tezosconnect specific HTTP headers when FireFly makes requests to Tezosconnectstringfirefly
prefixShortThe prefix that will be used for Tezosconnect specific query parameters when FireFly makes requests to Tezosconnectstringfly
requestTimeoutThe maximum amount of time that a request is allowed to remain opentime.Duration30s
tlsHandshakeTimeoutThe maximum amount of time to wait for a successful TLS handshaketime.Duration10s
topicThe websocket listen topic that the node should register on, which is important if there are multiple nodes using a single tezosconnectstring<nil>
urlThe URL of the Tezosconnect instanceURL string<nil>
+

plugins.blockchain[].tezos.tezosconnect.auth

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordPasswordstring<nil>
usernameUsernamestring<nil>
+

plugins.blockchain[].tezos.tezosconnect.backgroundStart

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
enabledStart the Tezosconnect plugin in the background and enter retry loop if failed to startboolean<nil>
factorSet the factor by which the delay increases when retryingfloat322
initialDelayDelay between restarts in the case where we retry to restart the tezos plugintime.Duration5s
maxDelayMax delay between restarts in the case where we retry to restart the tezos plugintime.Duration1m
+

plugins.blockchain[].tezos.tezosconnect.proxy

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
urlOptional HTTP proxy server to use when connecting to TezosconnectURL string<nil>
+

plugins.blockchain[].tezos.tezosconnect.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
countThe maximum number of times to retryint5
enabledEnables retriesbooleanfalse
errorStatusCodeRegexThe regex that the error response status code must match to trigger retrystring<nil>
initWaitTimeThe initial retry delaytime.Duration250ms
maxWaitTimeThe maximum retry delaytime.Duration30s
+

plugins.blockchain[].tezos.tezosconnect.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

plugins.blockchain[].tezos.tezosconnect.ws

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
connectionTimeoutThe amount of time to wait while establishing a connection (or auto-reconnection)time.Duration45s
heartbeatIntervalThe amount of time to wait between heartbeat signals on the WebSocket connectiontime.Duration30s
initialConnectAttemptsThe number of attempts FireFly will make to connect to the WebSocket when starting up, before failingint5
pathThe WebSocket sever URL to which FireFly should connectWebSocket URL string<nil>
readBufferSizeThe size in bytes of the read buffer for the WebSocket connectionBytesSize16Kb
urlURL to use for WebSocket - overrides url one level up (in the HTTP config)string<nil>
writeBufferSizeThe size in bytes of the write buffer for the WebSocket connectionBytesSize16Kb
+

plugins.database[]

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
nameThe name of the Database pluginstring<nil>
typeThe type of the configured Database pluginstring<nil>
+

plugins.database[].postgres

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
maxConnIdleTimeThe maximum amount of time a database connection can be idletime.Duration1m
maxConnLifetimeThe maximum amount of time to keep a database connection opentime.Duration<nil>
maxConnsMaximum connections to the databaseint50
maxIdleConnsThe maximum number of idle connections to the databaseint<nil>
urlThe PostgreSQL connection string for the databasestring<nil>
+

plugins.database[].postgres.migrations

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
autoEnables automatic database migrationsbooleanfalse
directoryThe directory containing the numerically ordered migration DDL files to apply to the databasestring./db/migrations/postgres
+

plugins.database[].sqlite3

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
maxConnIdleTimeThe maximum amount of time a database connection can be idletime.Duration1m
maxConnLifetimeThe maximum amount of time to keep a database connection opentime.Duration<nil>
maxConnsMaximum connections to the databaseint1
maxIdleConnsThe maximum number of idle connections to the databaseint<nil>
urlThe SQLite connection string for the databasestring<nil>
+

plugins.database[].sqlite3.migrations

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
autoEnables automatic database migrationsbooleanfalse
directoryThe directory containing the numerically ordered migration DDL files to apply to the databasestring./db/migrations/sqlite
+

plugins.dataexchange[]

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
nameThe name of the configured Data Exchange pluginstring<nil>
typeThe Data Exchange plugin to usestring<nil>
+

plugins.dataexchange[].ffdx

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
connectionTimeoutThe maximum amount of time that a connection is allowed to remain with no data transmittedtime.Duration30s
expectContinueTimeoutSee ExpectContinueTimeout in the Go docstime.Duration1s
headersAdds custom headers to HTTP requestsmap[string]string<nil>
idleTimeoutThe max duration to hold a HTTP keepalive connection between callstime.Duration475ms
initEnabledInstructs FireFly to always post all current nodes to the /init API before connecting or reconnecting to the connectorbooleanfalse
manifestEnabledDetermines whether to require+validate a manifest from other DX instances in the network. Must be supported by the connectorstringfalse
maxConnsPerHostThe max number of connections, per unique hostname. Zero means no limitint0
maxIdleConnsThe max number of idle connections to hold pooledint100
passthroughHeadersEnabledEnable passing through the set of allowed HTTP request headersbooleanfalse
requestTimeoutThe maximum amount of time that a request is allowed to remain opentime.Duration30s
tlsHandshakeTimeoutThe maximum amount of time to wait for a successful TLS handshaketime.Duration10s
urlThe URL of the Data Exchange instanceURL string<nil>
+

plugins.dataexchange[].ffdx.auth

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordPasswordstring<nil>
usernameUsernamestring<nil>
+

plugins.dataexchange[].ffdx.backgroundStart

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
enabledStart the data exchange plugin in the background and enter retry loop if failed to startbooleanfalse
factorSet the factor by which the delay increases when retryingfloat322
initialDelayDelay between restarts in the case where we retry to restart the data exchange plugintime.Duration5s
maxDelayMax delay between restarts in the case where we retry to restart the data exchange plugintime.Duration1m
+

plugins.dataexchange[].ffdx.eventRetry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
factorThe retry backoff factor, for event processingfloat322
initialDelayThe initial retry delay, for event processingtime.Duration50ms
maxDelayThe maximum retry delay, for event processingtime.Duration30s
+

plugins.dataexchange[].ffdx.proxy

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
urlOptional HTTP proxy server to use when connecting to the Data ExchangeURL string<nil>
+

plugins.dataexchange[].ffdx.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
countThe maximum number of times to retryint5
enabledEnables retriesbooleanfalse
errorStatusCodeRegexThe regex that the error response status code must match to trigger retrystring<nil>
initWaitTimeThe initial retry delaytime.Duration250ms
maxWaitTimeThe maximum retry delaytime.Duration30s
+

plugins.dataexchange[].ffdx.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

plugins.dataexchange[].ffdx.ws

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
connectionTimeoutThe amount of time to wait while establishing a connection (or auto-reconnection)time.Duration45s
heartbeatIntervalThe amount of time to wait between heartbeat signals on the WebSocket connectiontime.Duration30s
initialConnectAttemptsThe number of attempts FireFly will make to connect to the WebSocket when starting up, before failingint5
pathThe WebSocket sever URL to which FireFly should connectWebSocket URL string<nil>
readBufferSizeThe size in bytes of the read buffer for the WebSocket connectionBytesSize16Kb
urlURL to use for WebSocket - overrides url one level up (in the HTTP config)string<nil>
writeBufferSizeThe size in bytes of the write buffer for the WebSocket connectionBytesSize16Kb
+

plugins.identity[]

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
nameThe name of a configured Identity pluginstring<nil>
typeThe type of a configured Identity pluginstring<nil>
+

plugins.sharedstorage[]

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
nameThe name of the Shared Storage plugin to usestring<nil>
typeThe Shared Storage plugin to usestring<nil>
+

plugins.sharedstorage[].ipfs.api

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
connectionTimeoutThe maximum amount of time that a connection is allowed to remain with no data transmittedtime.Duration30s
expectContinueTimeoutSee ExpectContinueTimeout in the Go docstime.Duration1s
headersAdds custom headers to HTTP requestsmap[string]string<nil>
idleTimeoutThe max duration to hold a HTTP keepalive connection between callstime.Duration475ms
maxConnsPerHostThe max number of connections, per unique hostname. Zero means no limitint0
maxIdleConnsThe max number of idle connections to hold pooledint100
passthroughHeadersEnabledEnable passing through the set of allowed HTTP request headersbooleanfalse
requestTimeoutThe maximum amount of time that a request is allowed to remain opentime.Duration30s
tlsHandshakeTimeoutThe maximum amount of time to wait for a successful TLS handshaketime.Duration10s
urlThe URL for the IPFS APIURL string<nil>
+

plugins.sharedstorage[].ipfs.api.auth

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordPasswordstring<nil>
usernameUsernamestring<nil>
+

plugins.sharedstorage[].ipfs.api.proxy

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
urlOptional HTTP proxy server to use when connecting to the IPFS APIURL string<nil>
+

plugins.sharedstorage[].ipfs.api.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
countThe maximum number of times to retryint5
enabledEnables retriesbooleanfalse
errorStatusCodeRegexThe regex that the error response status code must match to trigger retrystring<nil>
initWaitTimeThe initial retry delaytime.Duration250ms
maxWaitTimeThe maximum retry delaytime.Duration30s
+

plugins.sharedstorage[].ipfs.api.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

plugins.sharedstorage[].ipfs.gateway

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
connectionTimeoutThe maximum amount of time that a connection is allowed to remain with no data transmittedtime.Duration30s
expectContinueTimeoutSee ExpectContinueTimeout in the Go docstime.Duration1s
headersAdds custom headers to HTTP requestsmap[string]string<nil>
idleTimeoutThe max duration to hold a HTTP keepalive connection between callstime.Duration475ms
maxConnsPerHostThe max number of connections, per unique hostname. Zero means no limitint0
maxIdleConnsThe max number of idle connections to hold pooledint100
passthroughHeadersEnabledEnable passing through the set of allowed HTTP request headersbooleanfalse
requestTimeoutThe maximum amount of time that a request is allowed to remain opentime.Duration30s
tlsHandshakeTimeoutThe maximum amount of time to wait for a successful TLS handshaketime.Duration10s
urlThe URL for the IPFS GatewayURL string<nil>
+

plugins.sharedstorage[].ipfs.gateway.auth

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordPasswordstring<nil>
usernameUsernamestring<nil>
+

plugins.sharedstorage[].ipfs.gateway.proxy

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
urlOptional HTTP proxy server to use when connecting to the IPFS GatewayURL string<nil>
+

plugins.sharedstorage[].ipfs.gateway.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
countThe maximum number of times to retryint5
enabledEnables retriesbooleanfalse
errorStatusCodeRegexThe regex that the error response status code must match to trigger retrystring<nil>
initWaitTimeThe initial retry delaytime.Duration250ms
maxWaitTimeThe maximum retry delaytime.Duration30s
+

plugins.sharedstorage[].ipfs.gateway.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

plugins.tokens[]

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
broadcastNameThe name to be used in broadcast messages related to this token plugin, if it differs from the local plugin namestring<nil>
nameA name to identify this token pluginstring<nil>
typeThe type of the token plugin to usestring<nil>
+

plugins.tokens[].fftokens

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
connectionTimeoutThe maximum amount of time that a connection is allowed to remain with no data transmittedtime.Duration30s
expectContinueTimeoutSee ExpectContinueTimeout in the Go docstime.Duration1s
headersAdds custom headers to HTTP requestsmap[string]string<nil>
idleTimeoutThe max duration to hold a HTTP keepalive connection between callstime.Duration475ms
maxConnsPerHostThe max number of connections, per unique hostname. Zero means no limitint0
maxIdleConnsThe max number of idle connections to hold pooledint100
passthroughHeadersEnabledEnable passing through the set of allowed HTTP request headersbooleanfalse
requestTimeoutThe maximum amount of time that a request is allowed to remain opentime.Duration30s
tlsHandshakeTimeoutThe maximum amount of time to wait for a successful TLS handshaketime.Duration10s
urlThe URL of the token connectorURL string<nil>
+

plugins.tokens[].fftokens.auth

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordPasswordstring<nil>
usernameUsernamestring<nil>
+

plugins.tokens[].fftokens.backgroundStart

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
enabledStart the tokens plugin in the background and enter retry loop if failed to startbooleanfalse
factorSet the factor by which the delay increases when retryingfloat322
initialDelayDelay between restarts in the case where we retry to restart the token plugintime.Duration5s
maxDelayMax delay between restarts in the case where we retry to restart the token plugintime.Duration1m
+

plugins.tokens[].fftokens.eventRetry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
factorThe retry backoff factor, for event processingfloat322
initialDelayThe initial retry delay, for event processingtime.Duration50ms
maxDelayThe maximum retry delay, for event processingtime.Duration30s
+

plugins.tokens[].fftokens.proxy

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
urlOptional HTTP proxy server to use when connecting to the token connectorURL string<nil>
+

plugins.tokens[].fftokens.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
countThe maximum number of times to retryint5
enabledEnables retriesbooleanfalse
errorStatusCodeRegexThe regex that the error response status code must match to trigger retrystring<nil>
initWaitTimeThe initial retry delaytime.Duration250ms
maxWaitTimeThe maximum retry delaytime.Duration30s
+

plugins.tokens[].fftokens.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

plugins.tokens[].fftokens.ws

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
connectionTimeoutThe amount of time to wait while establishing a connection (or auto-reconnection)time.Duration45s
heartbeatIntervalThe amount of time to wait between heartbeat signals on the WebSocket connectiontime.Duration30s
initialConnectAttemptsThe number of attempts FireFly will make to connect to the WebSocket when starting up, before failingint5
pathThe WebSocket sever URL to which FireFly should connectWebSocket URL string<nil>
readBufferSizeThe size in bytes of the read buffer for the WebSocket connectionBytesSize16Kb
urlURL to use for WebSocket - overrides url one level up (in the HTTP config)string<nil>
writeBufferSizeThe size in bytes of the write buffer for the WebSocket connectionBytesSize16Kb
+

privatemessaging.batch

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
agentTimeoutHow long to keep around a batching agent for a sending identity before disposaltime.Duration2m
payloadLimitThe maximum payload size of a private message Data Exchange payloadBytesSize800Kb
sizeThe maximum number of messages in a batch for private messagesint200
timeoutThe timeout to wait for a batch to fill, before sendingtime.Duration1s
+

privatemessaging.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
factorThe retry backoff factorfloat322
initDelayThe initial retry delaytime.Duration100ms
maxDelayThe maximum retry delaytime.Duration30s
+

spi

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
addressThe IP address on which the admin HTTP API should listenIP Address string127.0.0.1
enabledEnables the admin HTTP APIbooleanfalse
portThe port on which the admin HTTP API should listenint5001
publicURLThe fully qualified public URL for the admin API. This is used for building URLs in HTTP responses and in OpenAPI Spec generationURL string<nil>
readTimeoutThe maximum time to wait when reading from an HTTP connectiontime.Duration15s
shutdownTimeoutThe maximum amount of time to wait for any open HTTP requests to finish before shutting down the HTTP servertime.Duration10s
writeTimeoutThe maximum time to wait when writing to an HTTP connectiontime.Duration15s
+

spi.auth

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
typeThe auth plugin to use for server side authentication of requestsstring<nil>
+

spi.auth.basic

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
passwordfileThe path to a .htpasswd file to use for authenticating requests. Passwords should be hashed with bcrypt.string<nil>
+

spi.tls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
caFileThe path to the CA file for TLS on this APIstring<nil>
certFileThe path to the certificate file for TLS on this APIstring<nil>
clientAuthEnables or disables client auth for TLS on this APIstring<nil>
enabledEnables or disables TLS on this APIbooleanfalse
insecureSkipHostVerifyWhen to true in unit test development environments to disable TLS verification. Use with extreme cautionboolean<nil>
keyFileThe path to the private key file for TLS on this APIstring<nil>
requiredDNAttributesA 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)map[string]string<nil>
+

spi.ws

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
blockedWarnIntervalHow often to log warnings in core, when an admin change event listener falls behind the stream they requested and misses eventstime.Duration1m
eventQueueLengthServer-side queue length for events waiting for delivery over an admin change event listener websocketint250
readBufferSizeThe size in bytes of the read buffer for the WebSocket connectionBytesSize16Kb
writeBufferSizeThe size in bytes of the write buffer for the WebSocket connectionBytesSize16Kb
+

subscription

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
maxThe maximum number of pre-defined subscriptions that can exist (note for high fan-out consider connecting a dedicated pub/sub broker to the dispatcher)int500
+

subscription.defaults

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
batchSizeDefault read ahead to enable for subscriptions that do not explicitly configure readaheadint50
batchTimeoutDefault batch timeoutint50ms
+

subscription.events

+ + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
maxScanLengthThe maximum number of events a search for historical events matching a subscription will index from the databaseint1000
+

subscription.retry

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
factorThe retry backoff factorfloat322
initDelayThe initial retry delaytime.Duration250ms
maxDelayThe maximum retry delaytime.Duration30s
+

transaction.writer

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
batchMaxTransactionsThe maximum number of transaction inserts to include in a batchint100
batchTimeoutHow long to wait for more transactions to arrive before flushing the batchtime.Duration10ms
countThe number of message writer workersint5
+

ui

+ + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionTypeDefault Value
enabledEnables the web user interfacebooleantrue
pathThe file system path which contains the static HTML, CSS, and JavaScript files for the user interfacestring<nil>
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/events/index.html b/v1.3.1/reference/events/index.html new file mode 100644 index 000000000..eec6f7a6e --- /dev/null +++ b/v1.3.1/reference/events/index.html @@ -0,0 +1,3874 @@ + + + + + + + + + + + + + + + + + + + + + + + Event Bus - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Event Bus

+

FireFly Event Bus

+

Hyperledger FireFly Event Bus

+

The FireFly event bus provides your application with a single stream of events +from all of the back-end services that plug into FireFly.

+

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.

+

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 namespace, or can use server-side filtering to +only receive a sub-set of events.

+

The event bus reliably keeps track of which events have been delivered to which +applications, via an offset into the main event stream that is updated +each time an application acknowledges receipt of events over its subscription.

+

Event-Driven Application Architecture

+

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.

+

This requires an event-driven programming model.

+

You will find an event-driven model at the core of every blockchain +Smart Contract technology.

+

This event-driven approach is unavoidable regardless of how much of +your business data & logic can be directly stored/processed +on-chain, vs. off-chain.

+

So Hyperledger FireFly aims to provide you with the tools to easily +manage this model throughout your decentralized application stack.

+

Event Driven Programming Model

+

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.

+
+

FireFly comes with a built in event processor for Token transfers & +approvals, that implements this pattern to maintain balances, and +transaction history in a rich query off-chain data cache.

+
+

Decentralized Event Processing

+

In a decentralized system, you need to consider that each organization +runs its own applications, and has its own private database.

+

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.

+

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

+

FireFly Event Model

+

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

+

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.

+

Let's look at a couple of examples.

+

Example 1: A fungible token balance transfer

+

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.

+

This means the transaction must be backed by a blockchain verifiable by all participants +on the network that could hold balances of that token.

+

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.

+

Example 2: A step in a multi-party business process

+

Here it is likely you want to restrict visibility of the data to just the parties directly +involved in the business process.

+

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.

+

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.

+

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.

+

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.

+
+

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.

+
+

Privacy groups and late join

+

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.

+

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.

+
+

Using a single Ethereum permissioned side-chain for example.

+
+

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.

+
+

Using Hyperledger Fabric channels for example.

+
+

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.

+

These private data exchanges can also be coordinated with most sophisticated +on-chain transactions, such as token transfers.

+

Event Types

+

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.

+

All events in FireFly share a common base structure, regardless of their type. +They are then linked (via a reference) to an object that contains detailed +information.

+

The categories of event your application can receive are as follows:

+
+

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.

+
+

Blockchain events

+

FireFly allows your application to subscribe to any event from a blockchain +smart contract.

+

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

+

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

+

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

+

Check out the Custom Contracts Tutorial for +a walk-through of how to set up listeners for the events from your smart contracts.

+

FireFly automatically establishes listeners for some blockchain events:

+
    +
  • +

    Events from the FireFly BatchPin contract that is used to pin identities, + off-chain data broadcast and private messaging to the blockchain.

    +
    • +
  • +

    Events from Token contracts, for which a Token Pool + has been configured. These events are detected indirectly via the token connector.

    +
    • +
+

Token events

+

FireFly provides a Wallet API, that is pluggable to multiple token implementations +without needing to change your app.

+

The pluggable API/Event interface allows all kinds of technical implementations +of tokens to be fitted into a common framework.

+

The following wallet operations are supported. These are universal to all +token implementations - NFTs and fungible tokens alike:

+
    +
  • Mint
    • +
  • Burn
    • +
  • Transfer
    • +
  • Approve
    • +
+

FireFly processes, indexes and stores the events associated with these actions, +for any Token Pool that has been configured on the FireFly node.

+

See Token Transfer and Token Approval +for more information on the individual operations.

+

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.

+

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.

+

Message events: on-chain / off-chain coordinated

+

Event aggregation between data arriving off-chain, and the associated ordered +proof/transaction events being confirmed on-chain, is a complex orchestration task.

+

The universal order and additional transaction logic on-chain must be the +source of truth for when and how an event is processed.

+

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.

+

They might arrive in any order, and no further events can be processed on that business +transaction until the data is available.

+

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.

+

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 topic have been processed successfully by your application.

+

Your application just needs to:

+
    +
  1. Choose a suitable topic for your messages that determines the ordered stream + it is part of. Such as a business transaction identifier.
    2. +
  2. Make sure the application does not acknowledge a message, until it has finished + processing it.
    3. +
+
+

See Message for more information

+
+

Transaction submission events

+

These events are emitted each time a new transaction is initiated via the Firefly API.

+

These events are only emitted on the local FireFly node that initiates an activity.

+

For more information about FireFly Transactions, and how they relate to blockchain +transactions, see Transaction.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/firefly_interface_format/index.html b/v1.3.1/reference/firefly_interface_format/index.html new file mode 100644 index 000000000..74a635c70 --- /dev/null +++ b/v1.3.1/reference/firefly_interface_format/index.html @@ -0,0 +1,3748 @@ + + + + + + + + + + + + + + + + + + + + + + + FireFly Interface Format - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

FireFly Interface Format

+

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.

+

Overview

+

There are four required fields when broadcasting a contract interface in FireFly: a name, a version, a list of methods, and a list of events. A namespace field will also be filled in automatically based on the URL path parameter. Here is an example of the structure of the required fields:

+
{
+  "name": "example",
+  "version": "v1.0.0",
+  "methods": [],
+  "events": []
+}
+
+
+

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.

+
+

Method

+

Let's look at a what goes inside the methods array now. It is also a JSON object that has a name, a list of params which are the arguments the function will take and a list of returns which are the return values of the function. It also has an optional description which can be helpful in OpenAPI Spec generation. Finally, it has an optional details 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.

+
{
+  "name": "add",
+  "description": "Add two numbers together",
+  "params": [],
+  "returns": [],
+  "details": {}
+}
+
+

Event

+

What goes into the events array is very similar. It is also a JSON object that has a name and a list of params. The difference is that events don't have returns. Arguments that are passed to the event when it is emitted are in params. It also has an optional description which can be helpful in OpenAPI Spec generation. Finally, it has an optional details 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.

+
{
+  "name": "added",
+  "description": "An event that occurs when numbers have been added",
+  "params": [],
+  "details": {}
+}
+
+

Param

+

Both methods, and events have lists of params or returns, and the type of JSON object that goes in each of these arrays is the same. It is simply a JSON object with a name and a schema. There is also an optional details field that is passed to the blockchain plugin for blockchain specific requirements.

+
{
+  "name": "x",
+  "schema": {
+    "type": "integer",
+    "details": {}
+  }
+}
+
+

Schema

+

The param schema 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.

+

The schema field accepts JSON Schema (version 2020-12) with several additional requirements:

+
    +
  • A type field is always mandatory
    • +
  • The list of valid types is:
    • +
  • boolean
    • +
  • integer
    • +
  • string
    • +
  • object
    • +
  • array
    • +
  • Blockchain plugins can add their own specific requirements to this list of validation rules
    • +
+
+

NOTE: Floats or decimals are not currently accepted because certain underlying blockchains (e.g. Ethereum) only allow integers

+
+

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 details field, if there is a compatible type mapping between the two.

+

Schema details

+

+The details field is quite important in some cases. Because the details 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 details field.

+

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:

+
{
+  "type": "uint256",
+  "internalType": "uint256",
+  "indexed": false
+}
+
+

Automated generation of FireFly Interfaces

+

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.

+

For an example of using this endpoint with a specific Ethereum contract, please see the Tutorial to Work with custom smart contracts.

+

Full Example

+

Putting it all together, here is a full example of the FireFly Interface format with all the fields filled in:

+
{
+  "namespace": "default",
+  "name": "SimpleStorage",
+  "description": "A simple smart contract that stores and retrieves an integer on-chain",
+  "version": "v1.0.0",
+  "methods": [
+    {
+      "name": "get",
+      "description": "Retrieve the value of the stored integer",
+      "params": [],
+      "returns": [
+        {
+          "name": "output",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "uint256",
+              "internalType": "uint256"
+            }
+          }
+        }
+      ],
+      "details": {
+        "stateMutability": "viewable"
+      }
+    },
+    {
+      "name": "set",
+      "description": "Set the stored value on-chain",
+      "params": [
+        {
+          "name": "newValue",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "uint256",
+              "internalType": "uint256"
+            }
+          }
+        }
+      ],
+      "returns": [],
+      "details": {
+        "stateMutability": "payable"
+      }
+    }
+  ],
+  "events": [
+    {
+      "name": "Changed",
+      "description": "An event that is fired when the stored integer value changes",
+      "params": [
+        {
+          "name": "from",
+          "schema": {
+            "type": "string",
+            "details": {
+              "type": "address",
+              "internalType": "address",
+              "indexed": true
+            }
+          }
+        },
+        {
+          "name": "value",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "uint256",
+              "internalType": "uint256"
+            }
+          }
+        }
+      ],
+      "details": {}
+    }
+  ]
+}
+
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/idempotency/index.html b/v1.3.1/reference/idempotency/index.html new file mode 100644 index 000000000..7e1c31ced --- /dev/null +++ b/v1.3.1/reference/idempotency/index.html @@ -0,0 +1,3584 @@ + + + + + + + + + + + + + + + + + + + + + + + Idempotency Keys - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Idempotency Keys

+

Idempotency

+

The transaction submission REST APIs of Hyperledger FireFly are idempotent.

+

Idempotent APIs allow an application to safely submit a request multiple times, and for the transaction +to only be accepted and executed once.

+

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.

+

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.

+

In order for Hyperledger FireFly to deduplicate transactions, and make them idempotent, the application +must supply an idempotencyKey on each API request.

+

FireFly Idempotency Keys

+

Idempotency Keys Architecture

+

The caller of the API specifies its own unique identifier (an arbitrary string up to 256 characters) +that uniquely identifies the request, in the idempotencyKey field of the API.

+

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 409 Conflict HTTP code.

+

Examples of how an app might construct such an idempotencyKey include:

+
    +
  • Unique business identifiers from the request that comes into its API up-stream - passing idempotency along the chain
    • +
  • 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.
    +

    Be careful of cases where the business data might not be unique - like a transfer of 10 coins from A to B.

    +

    Such a transfer could happen multiple times, and each would be a separate business transaction.

    +

    Where as transfer with invoice number abcd1234 of 10 coins from A to B would be assured to be unique.

    +
    +
    • +
  • A unique identifier of a business transaction generated within the application and stored in its database before submission
    +

    This moves the challenge up one layer into your application. How does that unique ID get generated? Is that +itself idempotent?

    +
    +
    • +
+

Operation Idempotency

+

FireFly provides an idempotent interface downstream to connectors.

+

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.

+

Well formed connectors honor this idempotency key internally, ensuring that the end-to-end transaction submission is +idempotent.

+

Key examples of such connectors are EVMConnect and others built on the +Blockchain Connector Toolkit.

+

When an operation is retried automatically, the same idempotency key is re-used to avoid resubmission.

+

Short term retry

+

The FireFly core uses standard HTTP request code to communicate with all connector APIs.

+

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.

+

See Configuration Reference for more information.

+

Administrative operation retry

+

The operations/{operationId}/retry API can be called administratively to resubmit a +transaction that has reached Failed status, or otherwise been determined by an operator/monitor to be +unrecoverable within the connector.

+

In this case, the previous operation is marked Retried, a new operation ID is allocated, and +the operation is re-submitted to the connector with this new ID.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/identities/index.html b/v1.3.1/reference/identities/index.html new file mode 100644 index 000000000..01d7a893e --- /dev/null +++ b/v1.3.1/reference/identities/index.html @@ -0,0 +1,3720 @@ + + + + + + + + + + + + + + + + + + + + + + + Identities - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Identities

+

Overview

+

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.

+

Types of Identities

+

There are three types of identities:

+

org

+

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.

+

The root organization name and key must be defined in the FireFly config (once for every multi-party system). +It can be claimed with a POST to /network/organizations/self.

+

Organizations may have child identities of any type.

+

node

+

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

+

The node name must be defined in the FireFly config (once for every multi-party system). It can be +claimed with a POST to /network/nodes/self.

+

Nodes must be a child of an organization, and cannot have any child identities of their own.

+

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.

+

custom

+

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.

+

They can only have child identities which are also of type "custom".

+

Identity Claims

+

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.

+

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.

+

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.

+

Messaging

+

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.

+

Sender

+

When sending a message, the on-chain identity of the sender is controlled by the author and key fields.

+
    +
  • If both are blank, the root organization is assumed.
    • +
  • If author 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 key.
    • +
  • If key 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 author.
    • +
  • If author and key are both specified, they will be used as-is (can be used to send private messages with an unregistered blockchain key).
    • +
+

The resolved key will be used to sign the blockchain transaction, which establishes the sender's on-chain identity.

+

The sender's off-chain identity is always controlled by the node.name from the config along with the data exchange plugin.

+

Recipients

+

When specifying private message recipients, each one has an identity and a node.

+
    +
  • If identity alone is specified, it should be the DID of an org or custom identity. The first node owned by that identity or one of its + ancestors will be automatically selected.
    • +
  • If both identity and node are specified, they will be used as-is. The node should be a child of the given identity or one of its + ancestors.
    • +
+

The node in this case will control how the off-chain portion of the message is routed via data exchange.

+

Verification

+

When a message is received, FireFly verifies the following:

+
    +
  • The sender's author and key are specified in the message. The author must be a known org or custom identity. The key must match the + blockchain key that was used to sign the on-chain portion of the message. For broadcast messages, the key must match the registered + verifier for the author.
    • +
  • For private messages, the sending node (as reported by data exchange) must be a known node identity which is a child of the message's + author identity or one of its ancestors. The combination of the author identity and the node must also be found in the message group.
    • +
+

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

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/microservices/fftokens/index.html b/v1.3.1/reference/microservices/fftokens/index.html new file mode 100644 index 000000000..692369d46 --- /dev/null +++ b/v1.3.1/reference/microservices/fftokens/index.html @@ -0,0 +1,4851 @@ + + + + + + + + + + + + + + + + + + + + + + + fftokens - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

fftokens

+

Overview

+

fftokens is a protocol that can be implemented by token connector runtimes in order to be usable by the fftokens plugin in FireFly.

+

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.

+

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

+

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.

+

HTTP APIs

+

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 /api/v1 prefix.

+

POST /createpool

+

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 config).

+

In a multiparty network, this operation will only be performed by one of the parties, and FireFly will broadcast the result to the others.

+

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

+

Request

+
{
+  "type": "fungible",
+  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
+  "namespace": "default",
+  "name": "FFCoin",
+  "symbol": "FFC",
+  "data": "pool-metadata",
+  "requestId": "1",
+  "config": {}
+}
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
typestring enumThe 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.
signerstringThe signing identity to be used for the blockchain transaction, in a format understood by this connector.
namespacestringThe namespace of the token pool
namestring(OPTIONAL) If supported by this token contract, this is a requested name for the token pool. May be ignored at the connector's discretion.
symbolstring(OPTIONAL) If supported by this token contract, this is a requested symbol for the token pool. May be ignored at the connector's discretion.
requestIdstring(OPTIONAL) A unique identifier for this request. Will be included in the "receipt" websocket event to match receipts to requests.
datastring(OPTIONAL) A data string that should be returned in the connector's response to this creation request.
configobject(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.
+

Response

+

HTTP 200: pool creation was successful, and the pool details are returned in the response.

+

See Response Types: Token Pool

+

HTTP 202: request was accepted, but pool will be created asynchronously, with "receipt" and "token-pool" events sent later on the websocket.

+

See Response Types: Async Request

+

POST /activatepool

+

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.

+

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 poolLocator and config information passed in to this call, the pool should not get confirmed.

+

Request

+
{
+  "namespace": "default",
+  "poolLocator": "id=F1",
+  "poolData": "extra-pool-info",
+  "config": {}
+}
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
namespacestringThe namespace of the token pool
poolLocatorstringThe locator of the pool, as supplied by the output of the pool creation.
poolDatastring(OPTIONAL) A data string that should be permanently attached to this pool and returned in all events.
configobject(OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired. This should be the same config object that was passed when the pool was created.
+

Response

+

HTTP 200: pool activation was successful, and the pool details are returned in the response.

+

See Response Types: Token Pool

+

HTTP 202: request was accepted, but pool will be activated asynchronously, with "receipt" and "token-pool" events sent later on the websocket.

+

See Response Types: Async Request

+

HTTP 204: activation was successful - no separate receipt will be delivered, but "token-pool" event will be sent later on the websocket.

+

No body

+

POST /deactivatepool

+

Deactivate a token pool to stop receiving events and delete all blockchain listeners related to that pool.

+

Request

+
{
+  "namespace": "default",
+  "poolLocator": "id=F1",
+  "poolData": "extra-pool-info",
+  "config": {}
+}
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
namespacestringThe namespace of the token pool
poolLocatorstringThe locator of the pool, as supplied by the output of the pool creation.
poolDatastring(OPTIONAL) The data string that was attached to this pool at activation.
configobject(OPTIONAL) An arbitrary JSON object where the connector may accept additional parameters if desired.
+

Response

+

HTTP 204: deactivation was successful, and one or more listeners were deleted.

+

No body

+

HTTP 404: no blockchain listeners were found for the given pool information.

+

No body

+

POST /checkinterface

+

This is an optional (but recommended) API for token connectors. If implemented, support will be indicated by +the presence of the interfaceFormat field in all Token Pool responses.

+

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.

+

Request

+
{
+  "poolLocator": "id=F1",
+  "format": "abi",
+  "methods": [
+    {
+      "name": "burn",
+      "type": "function",
+      "inputs": [
+        {
+          "internalType": "uint256",
+          "name": "tokenId",
+          "type": "uint256"
+        }
+      ],
+      "outputs": [],
+      "stateMutability": "nonpayable"
+    },
+    ...
+  ]
+}
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
poolLocatorstringThe locator of the pool, as supplied by the output of the pool creation.
formatstring enumThe format of the data in this payload. Should match the interfaceFormat as supplied by the output of the pool creation.
methodsobject arrayA list of all the methods available on the interface underpinning this token pool, encoded in the format specified by format.
+

Response

+

HTTP 200: interface was successfully parsed, and methods of interest are returned in the body.

+

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 interface parameter).

+
{
+  "burn": {
+    "format": "abi",
+    "methods": [
+      {
+        "name": "burn",
+        "type": "function",
+        "inputs": [
+          {
+            "internalType": "uint256",
+            "name": "tokenId",
+            "type": "uint256"
+          }
+        ],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+      }
+    ]
+  },
+  "mint": { ... },
+  "transfer": { ... },
+  "approval": { ... }
+}
+
+

POST /mint

+

Mint new tokens.

+

Request

+
{
+  "namespace": "default",
+  "poolLocator": "id=F1",
+  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
+  "to": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
+  "amount": "10",
+  "tokenIndex": "1",
+  "uri": "ipfs://000000",
+  "requestId": "1",
+  "data": "transfer-metadata",
+  "config": {},
+  "interface": {}
+}
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
namespacestringThe namespace of the token pool
poolLocatorstringThe locator of the pool, as supplied by the output of the pool creation.
signerstringThe signing identity to be used for the blockchain transaction, in a format understood by this connector.
tostringThe identity to receive the minted tokens, in a format understood by this connector.
amountnumber stringThe amount of tokens to mint.
tokenIndexstring(OPTIONAL) For non-fungible tokens that require choosing an index at mint time, the index of the specific token to mint.
uristring(OPTIONAL) For non-fungible tokens that support choosing a URI at mint time, the URI to be attached to the token.
requestIdstring(OPTIONAL) A unique identifier for this request. Will be included in the "receipt" websocket event to match receipts to requests.
datastring(OPTIONAL) A data string that should be returned in the connector's response to this mint request.
configobject(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.
interfaceobject(OPTIONAL) Details on interface methods that are useful to this operation, as negotiated previously by a /checkinterface call.
+

Response

+

HTTP 202: request was accepted, but mint will occur asynchronously, with "receipt" and "token-mint" events sent later on the websocket.

+

See Response Types: Async Request

+

POST /burn

+

Burn tokens.

+

Request

+
{
+  "namespace": "default",
+  "poolLocator": "id=F1",
+  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
+  "from": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
+  "amount": "10",
+  "tokenIndex": "1",
+  "requestId": "1",
+  "data": "transfer-metadata",
+  "config": {},
+  "interface": {}
+}
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
namespacestringThe namespace of the token pool
poolLocatorstringThe locator of the pool, as supplied by the output of the pool creation.
signerstringThe signing identity to be used for the blockchain transaction, in a format understood by this connector.
fromstringThe identity that currently owns the tokens to be burned, in a format understood by this connector.
amountnumber stringThe amount of tokens to burn.
tokenIndexstring(OPTIONAL) For non-fungible tokens, the index of the specific token to burn.
requestIdstring(OPTIONAL) A unique identifier for this request. Will be included in the "receipt" websocket event to match receipts to requests.
datastring(OPTIONAL) A data string that should be returned in the connector's response to this burn request.
configobject(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.
interfaceobject(OPTIONAL) Details on interface methods that are useful to this operation, as negotiated previously by a /checkinterface call.
+

Response

+

HTTP 202: request was accepted, but burn will occur asynchronously, with "receipt" and "token-burn" events sent later on the websocket.

+

See Response Types: Async Request

+

POST /transfer

+

Transfer tokens from one address to another.

+

Request

+
{
+  "namespace": "default",
+  "poolLocator": "id=F1",
+  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
+  "from": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
+  "to": "0xb107ed9caa1323b7bc36e81995a4658ec2251951",
+  "amount": "1",
+  "tokenIndex": "1",
+  "requestId": "1",
+  "data": "transfer-metadata",
+  "config": {},
+  "interface": {}
+}
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
namespacestringThe namespace of the token pool
poolLocatorstringThe locator of the pool, as supplied by the output of the pool creation.
signerstringThe signing identity to be used for the blockchain transaction, in a format understood by this connector.
fromstringThe identity to be used for the source of the transfer, in a format understood by this connector.
tostringThe identity to be used for the destination of the transfer, in a format understood by this connector.
amountnumber stringThe amount of tokens to transfer.
tokenIndexstring(OPTIONAL) For non-fungible tokens, the index of the specific token to transfer.
requestIdstring(OPTIONAL) A unique identifier for this request. Will be included in the "receipt" websocket event to match receipts to requests.
datastring(OPTIONAL) A data string that should be returned in the connector's response to this transfer request.
configobject(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.
interfaceobject(OPTIONAL) Details on interface methods that are useful to this operation, as negotiated previously by a /checkinterface call.
+

Response

+

HTTP 202: request was accepted, but transfer will occur asynchronously, with "receipt" and "token-transfer" events sent later on the websocket.

+

See Response Types: Async Request

+

POST /approval

+

Approve another identity to manage tokens.

+

Request

+
{
+  "namespace": "default",
+  "poolLocator": "id=F1",
+  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
+  "operator": "0xb107ed9caa1323b7bc36e81995a4658ec2251951",
+  "approved": true,
+  "requestId": "1",
+  "data": "approval-metadata",
+  "config": {},
+  "interface": {}
+}
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
namespacestringThe namespace of the token pool
poolLocatorstringThe locator of the pool, as supplied by the output of the pool creation.
signerstringThe signing identity to be used for the blockchain transaction, in a format understood by this connector.
operatorstringThe identity to be approved (or unapproved) for managing the signer's tokens.
approvedbooleanWhether to approve (the default) or unapprove.
requestIdstring(OPTIONAL) A unique identifier for this request. Will be included in the "receipt" websocket event to match receipts to requests.
datastring(OPTIONAL) A data string that should be returned in the connector's response to this approval request.
configobject(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.
interfaceobject(OPTIONAL) Details on interface methods that are useful to this operation, as negotiated previously by a /checkinterface call.
+

Response

+

HTTP 202: request was accepted, but approval will occur asynchronously, with "receipt" and "token-approval" events sent later on the websocket.

+

See Response Types: Async Request

+

Websocket Commands

+

In order to start listening for events on a certain namespace, the client needs to send the start command. Clients should send this command every time they connect, or after an automatic reconnect.

+
{
+  "type": "start",
+  "namespace": "default"
+}
+
+

Websocket Events

+

A connector should expose a websocket at /api/ws. All emitted websocket events are a JSON string of the form:

+
{
+  "id": "event-id",
+  "event": "event-name",
+  "data": {}
+}
+
+

The event name will match one of the names listed below, and the data payload will correspond to the linked response object.

+

All events except the receipt event must be acknowledged by sending an ack of the form:

+
{
+  "event": "ack",
+  "data": {
+    "id": "event-id"
+  }
+}
+
+

Many messages may also be batched into a single websocket event of the form:

+
{
+  "id": "event-id",
+  "event": "batch",
+  "data": {
+    "events": [
+      {
+        "event": "event-name",
+        "data": {}
+      },
+      ...
+    ]
+  }
+}
+
+

Batched messages must be acked all at once using the ID of the batch.

+

receipt

+

An asynchronous operation has completed.

+

See Response Types: Receipt

+

token-pool

+

A new token pool has been created or activated.

+

See Response Types: Token Pool

+

token-mint

+

Tokens have been minted.

+

See Response Types: Token Transfer

+

token-burn

+

Tokens have been burned.

+

See Response Types: Token Transfer

+

token-transfer

+

Tokens have been transferred.

+

See Response Types: Token Transfer

+

token-approval

+

Token approvals have changed.

+

See Response Types: Token Approval

+

Response Types

+

Async Request

+

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.

+
{
+  "id": "b84ab27d-0d50-42a6-9c26-2fda5eb901ba"
+}
+
+

Receipt

+
  "headers": {
+    "type": "",
+    "requestId": ""
+  }
+  "transactionHash": "",
+  "errorMessage": ""
+}
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
headers.typestring enumThe type of this response. Should be "TransactionSuccess", "TransactionUpdate", or "TransactionFailed".
headers.requestIdstringThe ID of the request to which this receipt should correlate.
transactionHashstringThe unique identifier for the blockchain transaction which generated this receipt.
errorMessagestring(OPTIONAL) If this is a failure, contains details on the reason for the failure.
+

Token Pool

+
{
+  "namespace": "default",
+  "type": "fungible",
+  "data": "pool-metadata",
+  "poolLocator": "id=F1",
+  "standard": "ERC20",
+  "interfaceFormat": "abi",
+  "symbol": "FFC",
+  "decimals": 18,
+  "info": {},
+  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
+  "blockchain": {}
+}
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
namespacestringThe namespace of the token pool
typestring enumThe type of pool that was created.
datastringA copy of the data that was passed in on the creation request.
poolLocatorstringA 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).
standardstring(OPTIONAL) The name of a well-defined token standard to which this pool conforms.
interfaceFormatstring enum(OPTIONAL) If this connector supports the /checkinterface API, this is the interface format to be used for describing the interface underpinning this pool. Must be "abi" or "ffi".
symbolstring(OPTIONAL) The symbol for this token pool, if applicable.
decimalsnumber(OPTIONAL) The number of decimals used for balances in this token pool, if applicable.
infoobject(OPTIONAL) Additional information about the pool. Each connector may define the format for this object.
signerstring(OPTIONAL) If this operation triggered a blockchain transaction, the signing identity used for the transaction.
blockchainobject(OPTIONAL) If this operation triggered a blockchain transaction, contains details on the blockchain event in FireFly's standard blockchain event format.
+

Token Transfer

+

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.

+
{
+  "namespace": "default",
+  "id": "1",
+  "data": "transfer-metadata",
+  "poolLocator": "id=F1",
+  "poolData": "extra-pool-info",
+  "from": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
+  "to": "0xb107ed9caa1323b7bc36e81995a4658ec2251951",
+  "amount": "1",
+  "tokenIndex": "1",
+  "uri": "ipfs://000000",
+  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
+  "blockchain": {}
+}
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
namespacestringThe namespace of the token pool
idstringAn identifier for this transfer. Must be unique for every transfer within this pool.
datastringA 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).
poolLocatorstringThe locator of the pool, as supplied by the output of the pool creation.
poolDatastringThe extra data associated with the pool at pool activation.
fromstringThe identity used for the source of the transfer.
tostringThe identity used for the destination of the transfer.
amountnumber stringThe amount of tokens transferred.
tokenIndexstring(OPTIONAL) For non-fungible tokens, the index of the specific token transferred.
uristring(OPTIONAL) For non-fungible tokens, the URI attached to the token.
signerstring(OPTIONAL) If this operation triggered a blockchain transaction, the signing identity used for the transaction.
blockchainobject(OPTIONAL) If this operation triggered a blockchain transaction, contains details on the blockchain event in FireFly's standard blockchain event format.
+

Token Approval

+
{
+  "namespace": "default",
+  "id": "1",
+  "data": "transfer-metadata",
+  "poolLocator": "id=F1",
+  "poolData": "extra-pool-info",
+  "operator": "0xb107ed9caa1323b7bc36e81995a4658ec2251951",
+  "approved": true,
+  "subject": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A:0xb107ed9caa1323b7bc36e81995a4658ec2251951",
+  "info": {},
+  "signer": "0x0Ef1D0Dd56a8FB1226C0EaC374000B81D6c8304A",
+  "blockchain": {}
+}
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
namespacestringThe namespace of the token pool
idstringAn identifier for this approval. Must be unique for every approval within this pool.
datastringA 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).
poolLocatorstringThe locator of the pool, as supplied by the output of the pool creation.
poolDatastringThe extra data associated with the pool at pool activation.
operatorstringThe identity that was approved (or unapproved) for managing tokens.
approvedbooleanWhether this was an approval or unapproval.
subjectstringA 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.
infoobject(OPTIONAL) Additional information about the approval. Each connector may define the format for this object.
signerstring(OPTIONAL) If this operation triggered a blockchain transaction, the signing identity used for the transaction.
blockchainobject(OPTIONAL) If this operation triggered a blockchain transaction, contains details on the blockchain event in FireFly's standard blockchain event format.
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/namespaces/index.html b/v1.3.1/reference/namespaces/index.html new file mode 100644 index 000000000..1247422f1 --- /dev/null +++ b/v1.3.1/reference/namespaces/index.html @@ -0,0 +1,3736 @@ + + + + + + + + + + + + + + + + + + + + + + + Namespaces - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Namespaces

+

FireFly Namespaces Example

+

Introduction to Namespaces

+

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:

+
    +
  • Plugin and infrastructure components
    • +
  • API security
    • +
  • Identity broadcasting
    • +
  • On-chain data indexing
    • +
  • How datatypes, locations of on-chain contrats, etc. should be shared
    • +
+

They can be thought of in two basic modes:

+

Multi-party Namespaces

+

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.

+

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.

+

Gateway Namespaces

+

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.

+

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.

+

Configuration

+

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.

+

Below is an example plugin and namespace configuration containing both a multi-party and gateway namespace:

+
plugins:
+  database:
+  - name: database0
+    type: sqlite3
+    sqlite3:
+      migrations:
+        auto: true
+      url: /etc/firefly/db?_busy_timeout=5000
+  blockchain:
+  - name: blockchain0
+    type: ethereum
+    ethereum:
+      ethconnect:
+        url: http://ethconnect_0:8080
+        topic: "0"
+  - name: blockchain1
+    type: ethereum
+    ethereum:
+      ethconnect:
+        url: http://ethconnect_01:8080
+        topic: "0"
+  dataexchange:
+  - name: dataexchange0
+    type: ffdx
+    ffdx:
+      url: http://dataexchange_0:3000
+  sharedstorage:
+  - name: sharedstorage0
+    type: ipfs
+    ipfs:
+      api:
+        url: http://ipfs_0:5001
+      gateway:
+        url: http://ipfs_0:8080
+  tokens:
+  - name: erc20_erc721
+    broadcastName: erc20_erc721
+    type: fftokens
+    fftokens:
+      url: http://tokens_0_0:3000
+namespaces:
+  default: alpha
+  predefined:
+  - name: alpha
+    description: Default predefined namespace
+    defaultKey: 0x123456
+    plugins: [database0, blockchain0, dataexchange0, sharedstorage0, erc20_erc721]
+    multiparty:
+      networkNamespace: alpha
+      enabled: true
+      org:
+        name: org0
+        description: org0
+        key: 0x123456
+      node:
+        name: node0
+        description: node0
+      contract:
+        - location:
+            address: 0x4ae50189462b0e5d52285f59929d037f790771a6
+          firstEvent: 0
+        - location:
+            address: 0x3c1bef20a7858f5c2f78bda60796758d7cafff27
+          firstEvent: 5000
+  - name: omega
+    defaultkey: 0x48a54f9964d7ceede2d6a8b451bf7ad300c7b09f
+    description: Gateway namespace
+    plugins: [database0, blockchain1, erc20_erc721]
+
+

The namespaces.predefined object contains the follow sub-keys:

+
    +
  • defaultKey is a blockchain key used to sign transactions when none is specified (in multi-party mode, + defaults to the org key)
    • +
  • plugins is an array of plugin names to be activated for this namespace (defaults to + all available plugins if omitted)
    • +
  • multiparty.networkNamespace 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 name)
    • +
  • multiparty.enabled 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 org section at the root)
    • +
  • multiparty.org is the root org identity for this multi-party namespace (containing name, + description, and key)
    • +
  • multiparty.node is the local node identity for this multi-party namespace (containing name and + description)
    • +
  • multiparty.contract is an array of objects describing the location(s) of a FireFly multi-party + smart contract. Its children are blockchain-agnostic location and firstEvent 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.
    • +
+

Config Restrictions

+
    +
  • name must be unique on this node
    • +
  • for historical reasons, "ff_system" is a reserved string and cannot be used as a name or multiparty.networkNamespace
    • +
  • a database plugin is required for every namespace
    • +
  • if multiparty.enabled is true, plugins must include one each of blockchain, dataexchange, and + sharedstorage
    • +
  • if multiparty.enabled is false, plugins must not include dataexchange or sharedstorage
    • +
  • at most one of each type of plugin is allowed per namespace, except for tokens (which + may have many per namespace)
    • +
+

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.

+

Definitions

+

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.

+

Local Definitions

+

The following are all "definition" types in FireFly:

+
    +
  • datatype
    • +
  • group
    • +
  • token pool
    • +
  • contract interface
    • +
  • contract API
    • +
  • organization (deprecated)
    • +
  • node (deprecated)
    • +
  • identity claim
    • +
  • identity verification
    • +
  • identity update
    • +
+

For gateway namespaces, the APIs which create these definitions will become an immediate +local database insert, instead of performing a broadcast. Additional caveats:

+
    +
  • identities in this mode will not undergo any claim/verification process, + but will be created and stored locally
    • +
  • datatypes and groups will not be supported, as they are only useful in the context + of messaging (which is disabled in gateway namespaces)
    • +
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/tls/index.html b/v1.3.1/reference/tls/index.html new file mode 100644 index 000000000..d3c0aa71d --- /dev/null +++ b/v1.3.1/reference/tls/index.html @@ -0,0 +1,3549 @@ + + + + + + + + + + + + + + + + + + + + + + + TLS - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

TLS

+ +

TLS Overview

+

To enable TLS in Firefly, there is a configuration available to provide certificates and keys.

+

The common configuration is as such:

+
tls:
+  enabled: true/false # Toggle on or off TLS
+  caFile: <path to the CA file you want the client or server to trust>
+  certFile: <path to the cert file you want the client or server to use when performing authentication in mTLS>
+  keyFile: <path to the priavte key file you want the client or server to use when performing  authentication in mTLS>
+  clientAuth: true/false # Only applicable to the server side, to toggle on or off client authentication
+  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)
+
+

NOTE The CAs, certificates and keys have to be in PEM format.

+

Configuring TLS for the API server

+

Using the above configuration, we can place it under the http config and enable TLS or mTLS for any API call.

+

See this config section for details

+

Configuring TLS for the webhooks

+

Using the above configuration, we can place it under the events.webhooks config and enable TLS or mTLS for any webhook call.

+

See this config section for details

+

Configuring clients and websockets

+

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.

+

For example, if you wish to configure the ethereum blockchain connector with TLS you would look at this config section

+

For more clients, search in the configuration reference for a TLS section.

+

Enhancing validation of certificates

+

In the case where we want to verify that a specific client certificate has certain attributes we can use the requiredDNAtributes 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

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/batch/index.html b/v1.3.1/reference/types/batch/index.html new file mode 100644 index 000000000..a584b19a8 --- /dev/null +++ b/v1.3.1/reference/types/batch/index.html @@ -0,0 +1,3654 @@ + + + + + + + + + + + + + + + + + + + + + + + Batch - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Batch

+ + +

A batch bundles a number of off-chain messages, with associated data, into a single payload +for broadcast or private transfer.

+

This allows the transfer of many messages (hundreds) to be backed by a single blockchain +transaction. Thus making very efficient use of the blockchain.

+

The same benefit also applies to the off-chain transport mechanism.

+

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.

+

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.

+ + +

Example

+
{
+    "id": "894bc0ea-0c2e-4ca4-bbca-b4c39a816bbb",
+    "type": "private",
+    "namespace": "ns1",
+    "node": "5802ab80-fa71-4f52-9189-fb534de93756",
+    "group": "cd1fedb69fb83ad5c0c62f2f5d0b04c59d2e41740916e6815a8e063b337bd32e",
+    "created": "2022-05-16T01:23:16Z",
+    "author": "did:firefly:org/example",
+    "key": "0x0a989907dcd17272257f3ebcf72f4351df65a846",
+    "hash": "78d6861f860c8724468c9254b99dc09e7d9fd2d43f26f7bd40ecc9ee47be384d",
+    "payload": {
+        "tx": {
+            "type": "private",
+            "id": "04930d84-0227-4044-9d6d-82c2952a0108"
+        },
+        "messages": [],
+        "data": []
+    }
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the batchUUID
typeThe type of the batchFFEnum:
"broadcast"
"private"
namespaceThe namespace of the batchstring
nodeThe UUID of the node that generated the batchUUID
groupThe privacy group the batch is sent to, for private batchesBytes32
createdThe time the batch was sealedFFTime
authorThe DID of identity of the submitterstring
keyThe on-chain signing key used to sign the transactionstring
hashThe hash of the manifest of the batchBytes32
payloadBatch.payloadBatchPayload
+

BatchPayload

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
txBatchPayload.txTransactionRef
messagesBatchPayload.messagesMessage[]
dataBatchPayload.dataData[]
+

TransactionRef

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
typeThe type of the FireFly transactionFFEnum:
idThe UUID of the FireFly transactionUUID
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/blockchainevent/index.html b/v1.3.1/reference/types/blockchainevent/index.html new file mode 100644 index 000000000..34fcf19e1 --- /dev/null +++ b/v1.3.1/reference/types/blockchainevent/index.html @@ -0,0 +1,3660 @@ + + + + + + + + + + + + + + + + + + + + + + + BlockchainEvent - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

BlockchainEvent

+ + +

Blockchain Events are detected by the blockchain plugin:

+
    +
  1. When a ContractListener has been + configured against any custom smart contract through the FireFly API
    2. +
  2. 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
    3. +
  3. 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).
    4. +
+

Protocol ID

+

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.

+

How to describe that position contains blockchain specifics - depending on how +a particular blockchain represents transactions, blocks and events (or "logs").

+

So FireFly is flexible with a string protocolId 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.

+

An example protocolId string is: 000000000041/000020/000003

+
    +
  • 000000000041 - this is the block number
    • +
  • 000020 - this is the transaction index within that block
    • +
  • 000003 - this is the event (/log) index within that transaction
    • +
+

The string is alphanumerically sortable as a plain string;

+
+

Sufficient zero padding is included at each layer to support future expansion +without creating a string that would no longer sort correctly.

+
+ + +

Example

+
{
+    "id": "e9bc4735-a332-4071-9975-b1066e51ab8b",
+    "source": "ethereum",
+    "namespace": "ns1",
+    "name": "MyEvent",
+    "listener": "c29b4595-03c2-411a-89e3-8b7f27ef17bb",
+    "protocolId": "000000000048/000000/000000",
+    "output": {
+        "addr1": "0x55860105d6a675dbe6e4d83f67b834377ba677ad",
+        "value2": "42"
+    },
+    "info": {
+        "address": "0x57A9bE18CCB50D06B7567012AaF6031D669BBcAA",
+        "blockHash": "0xae7382ef2573553f517913b927d8b9691ada8d617266b8b16f74bb37aa78cae8",
+        "blockNumber": "48",
+        "logIndex": "0",
+        "signature": "Changed(address,uint256)",
+        "subId": "sb-e4d5efcd-2eba-4ed1-43e8-24831353fffc",
+        "timestamp": "1653048837",
+        "transactionHash": "0x34b0327567fefed09ac7b4429549bc609302b08a9cbd8f019a078ec44447593d",
+        "transactionIndex": "0x0"
+    },
+    "timestamp": "2022-05-16T01:23:15Z",
+    "tx": {
+        "blockchainId": "0x34b0327567fefed09ac7b4429549bc609302b08a9cbd8f019a078ec44447593d"
+    }
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID assigned to the event by FireFlyUUID
sourceThe blockchain plugin or token service that detected the eventstring
namespaceThe namespace of the listener that detected this blockchain eventstring
nameThe name of the event in the blockchain smart contractstring
listenerThe UUID of the listener that detected this event, or nil for built-in events in the system namespaceUUID
protocolIdAn alphanumerically sortable string that represents this event uniquely on the blockchain (convention for plugins is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX)string
outputThe data output by the event, parsed to JSON according to the interface of the smart contractJSONObject
infoDetailed blockchain specific information about the event, as generated by the blockchain connectorJSONObject
timestampThe time allocated to this event by the blockchain. This is the block timestamp for most blockchain connectorsFFTime
txIf 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 transactionBlockchainTransactionRef
+

BlockchainTransactionRef

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
typeThe type of the FireFly transactionFFEnum:
idThe UUID of the FireFly transactionUUID
blockchainIdThe blockchain transaction ID, in the format specific to the blockchain involved in the transaction. Not all FireFly transactions include a blockchainstring
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/contractapi/index.html b/v1.3.1/reference/types/contractapi/index.html new file mode 100644 index 000000000..e68a1fb95 --- /dev/null +++ b/v1.3.1/reference/types/contractapi/index.html @@ -0,0 +1,3763 @@ + + + + + + + + + + + + + + + + + + + + + + + ContractAPI - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

ContractAPI

+ + +

Contract APIs provide generated REST APIs for on-chain smart contracts.

+

API endpoints are generated to invoke or perform query operations against +each of the functions/methods implemented by the smart contract.

+

API endpoints are also provided to add listeners to the events of that +smart contract.

+
+

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 blockchain_event_received) that are emitted +for each detected blockchain event.

+

For more information see the Events reference section.

+
+

URL

+

The base path for your Contract API is:

+
    +
  • /api/v1/namespaces/{ns}/apis/{apiName}
    • +
+

For the default namespace, this can be shortened to:

+
    +
  • /api/v1/apis/{apiName}
    • +
+

FireFly Interface (FFI) and On-chain Location

+

Contract APIs are registered against:

+
    +
  1. +

    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.

    +
    2. +
  2. +

    An optional location 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 address of the Smart Contract for an Ethereum based blockchain, + or the name and channel for a Hyperledger Fabric based blockchain.

    +
    3. +
+

If the location is not specified on creation of the Contract API, then it must be +specified on each API call made to the Contract API endpoints.

+

OpenAPI V3 / Swagger Definitions

+

Each Contract API comes with an OpenAPI V3 / Swagger generated definition, which can +be downloaded from:

+
    +
  • /api/v1/namespaces/{namespaces}/apis/{apiName}/api/swagger.json
    • +
+

Swagger UI

+

A browser / exerciser UI for your API is also available on:

+
    +
  • /api/v1/namespaces/{namespaces}/apis/{apiName}/api
    • +
+ + +

Example

+
{
+    "id": "0f12317b-85a0-4a77-a722-857ea2b0a5fa",
+    "namespace": "ns1",
+    "interface": {
+        "id": "c35d3449-4f24-4676-8e64-91c9e46f06c4"
+    },
+    "location": {
+        "address": "0x95a6c4895c7806499ba35f75069198f45e88fc69"
+    },
+    "name": "my_contract_api",
+    "message": "b09d9f77-7b16-4760-a8d7-0e3c319b2a16",
+    "urls": {
+        "api": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/my_contract_api",
+        "openapi": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/my_contract_api/api/swagger.json",
+        "ui": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/my_contract_api/api"
+    },
+    "published": false
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the contract APIUUID
namespaceThe namespace of the contract APIstring
interfaceReference to the FireFly Interface definition associated with the contract APIFFIReference
locationIf 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 channelJSONAny
nameThe name that is used in the URL to access the APIstring
networkNameThe published name of the API within the multiparty networkstring
messageThe UUID of the broadcast message that was used to publish this API to the networkUUID
urlsThe URLs to use to access the APIContractURLs
publishedIndicates if the API is published to other members of the multiparty networkbool
+

FFIReference

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the FireFly interfaceUUID
nameThe name of the FireFly interfacestring
versionThe version of the FireFly interfacestring
+

ContractURLs

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
apiThe URL to use to invoke the APIstring
openapiThe URL to download the OpenAPI v3 (Swagger) description for the API generated in JSON or YAML formatstring
uiThe URL to use in a web browser to access the SwaggerUI explorer/exerciser for the APIstring
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/contractlistener/index.html b/v1.3.1/reference/types/contractlistener/index.html new file mode 100644 index 000000000..51bd11261 --- /dev/null +++ b/v1.3.1/reference/types/contractlistener/index.html @@ -0,0 +1,4011 @@ + + + + + + + + + + + + + + + + + + + + + + + ContractListener - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

ContractListener

+ + +

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.

+

Check out the Custom Contracts Tutorial for +a walk-through of how to set up listeners for the events from your smart contracts.

+

See below for a deep dive into the format of contract listeners and important concepts to understand when managing them.

+

Event filters

+

Multiple filters

+

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:

+
    +
  • a reference to a specific blockchain event to listen for
    • +
  • (optional) a specific location/address to listen from
    • +
  • a connector-specific signature (generated from the event and the location)
    • +
+

In addition to this list of multiple filters, the listener specifies a single topic to identify the stream of events.

+

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.

+

Single filter

+

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:

+
    +
  • a reference to a specific blockchain event to listen for
    • +
  • (optional) a specific location/address to listen from
    • +
  • a connector-specific signature (generated from the event), which allows you to easily identify and search for the contact listener for an event
    • +
  • a topic which determines the ordered stream that these events are part of
    • +
+

For backwards compatibility, this format is still supported by the API.

+

Signature strings

+

String format

+

Each filter is identified by a generated signature that matches a single event, and each contract listener is identified by a signature computed from its filters.

+

Ethereum provides a string standard for event signatures, of the form EventName(uint256,bytes). Prior to v1.3.1, the signature of each Ethereum contract listener would exactly follow this Ethereum format.

+

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 indexed. For example, while the following two Solidity events have the same signature, they are serialized differently due to the different placement of indexed parameters, and thus a listener must define both individually to be able to process them:

+
    +
  • ERC-20 Transfer
    • +
+
event Transfer(address indexed _from, address indexed _to, uint256 _value)
+
+
    +
  • ERC-721 Transfer
    • +
+
event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);
+
+

The two above are now expressed in the following manner by the Ethereum blockchain connector:

+
Transfer(address,address,uint256) [i=0,1]
+Transfer(address,address,uint256) [i=0,1,2]
+
+

The [i=] listing at the end of the signature indicates the position of all parameters that are marked as indexed.

+

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:

+
    +
  • Each filter signature is a combination of the location and the specific connector event signature, such as 0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]
    • +
  • Each contract listener signature is a concatenation of all the filter signatures, separated by ;
    • +
+

Duplicate filters

+

FireFly restricts the creation of a contract listener containing duplicate filters.

+

This includes the special case where one filter is a superset of another filter, due to a wildcard location.

+

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.

+

Duplicate listeners

+

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.

+

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.

+

Backwards compatibility

+

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.

+
    +
  • The response from all query APIs of listeners will continue to populate top-level event and location fields
    • +
  • The first entry from the filters array is duplicated to these fields
    • +
  • On input to create a new listener, the event and location fields are still supported
    • +
  • They function identically to supplying a filters array with a single entry
    • +
  • The signature field is preserved at the listener level
    • +
  • The format has been changed as described above
    • +
+

Input formats

+

The two input formats supported when creating a contract listener are shown below.

+

Muliple Filters

+
{
+  "filters": [
+    {
+      "interface": {
+        "id": "8bdd27a5-67c1-4960-8d1e-7aa31b9084d3"
+      },
+      "location": {
+        "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1"
+      },
+      "eventPath": "Changed"
+    },
+    {
+      "interface": {
+        "id": "8bdd27a5-67c1-4960-8d1e-7aa31b9084d3"
+      },
+      "location": {
+        "address": "0xa4ea5d0b6b2eaf194716f0cc73981939dca27da1"
+      },
+      "eventPath": "AnotherEvent"
+    }
+  ],
+  "options": {
+    "firstEvent": "newest"
+  },
+  "topic": "simple-storage"
+}
+
+

One filter (old format)

+
{
+  "interface": {
+    "id": "8bdd27a5-67c1-4960-8d1e-7aa31b9084d3"
+  },
+  "location": {
+    "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1"
+  },
+  "eventPath": "Changed",
+  "options": {
+    "firstEvent": "newest"
+  },
+  "topic": "simple-storage"
+}
+
+ + +

Example

+
{
+    "id": "d61980a9-748c-4c72-baf5-8b485b514d59",
+    "interface": {
+        "id": "ff1da3c1-f9e7-40c2-8d93-abb8855e8a1d"
+    },
+    "namespace": "ns1",
+    "name": "contract1_events",
+    "backendId": "sb-dd8795fc-a004-4554-669d-c0cf1ee2c279",
+    "location": {
+        "address": "0x596003a91a97757ef1916c8d6c0d42592630d2cf"
+    },
+    "created": "2022-05-16T01:23:15Z",
+    "event": {
+        "name": "Changed",
+        "description": "",
+        "params": [
+            {
+                "name": "x",
+                "schema": {
+                    "type": "integer",
+                    "details": {
+                        "type": "uint256",
+                        "internalType": "uint256"
+                    }
+                }
+            }
+        ]
+    },
+    "signature": "0x596003a91a97757ef1916c8d6c0d42592630d2cf:Changed(uint256)",
+    "topic": "app1_topic",
+    "options": {
+        "firstEvent": "newest"
+    },
+    "filters": [
+        {
+            "event": {
+                "name": "Changed",
+                "description": "",
+                "params": [
+                    {
+                        "name": "x",
+                        "schema": {
+                            "type": "integer",
+                            "details": {
+                                "type": "uint256",
+                                "internalType": "uint256"
+                            }
+                        }
+                    }
+                ]
+            },
+            "location": {
+                "address": "0x596003a91a97757ef1916c8d6c0d42592630d2cf"
+            },
+            "signature": "0x596003a91a97757ef1916c8d6c0d42592630d2cf:Changed(uint256)"
+        }
+    ]
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the smart contract listenerUUID
interfaceDeprecated: Please use 'interface' in the array of 'filters' insteadFFIReference
namespaceThe namespace of the listener, which defines the namespace of all blockchain events detected by this listenerstring
nameA descriptive name for the listenerstring
backendIdAn ID assigned by the blockchain connector to this listenerstring
locationDeprecated: Please use 'location' in the array of 'filters' insteadJSONAny
createdThe creation time of the listenerFFTime
eventDeprecated: Please use 'event' in the array of 'filters' insteadFFISerializedEvent
signatureA concatenation of all the stringified signature of the event and location, as computed by the blockchain pluginstring
topicA 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 needstring
optionsOptions that control how the listener subscribes to events from the underlying blockchainContractListenerOptions
filtersA 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.ListenerFilter[]
+

FFIReference

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the FireFly interfaceUUID
nameThe name of the FireFly interfacestring
versionThe version of the FireFly interfacestring
+

FFISerializedEvent

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
nameThe name of the eventstring
descriptionA description of the smart contract eventstring
paramsAn array of event parameter/argument definitionsFFIParam[]
detailsAdditional blockchain specific fields about this event from the original smart contract. Used by the blockchain plugin and for documentation generation.JSONObject
+

FFIParam

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
nameThe name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contractstring
schemaFireFly 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 detailJSONAny
+

ContractListenerOptions

+ + + + + + + + + + + + + + + +
Field NameDescriptionType
firstEventA 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'string
+

ListenerFilter

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
eventThe definition of the event, either provided in-line when creating the listener, or extracted from the referenced FFIFFISerializedEvent
locationA blockchain specific contract identifier. For example an Ethereum contract address, or a Fabric chaincode name and channelJSONAny
interfaceA reference to an existing FFI, containing pre-registered type information for the eventFFIReference
signatureThe stringified signature of the event and location, as computed by the blockchain pluginstring
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/data/index.html b/v1.3.1/reference/types/data/index.html new file mode 100644 index 000000000..3b9b11ed9 --- /dev/null +++ b/v1.3.1/reference/types/data/index.html @@ -0,0 +1,3754 @@ + + + + + + + + + + + + + + + + + + + + + + + Data - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Data

+ + +

Data is a uniquely identified piece of data available for retrieval or transfer.

+

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.

+

An UUID is allocated to each data resource.

+

A hash is also calculated as follows:

+
    +
  • If there is only data, the hash is of the value serialized as JSON with + no additional whitespace (order of the keys is retained from the original + upload order).
    • +
  • If there is only a blob attachment, the hash is of the blob data.
    • +
  • There is is both a blob and a value, then the hash is a hash of the + concatenation of a hash of the value and a hash of the blob.
    • +
+

Value - JSON data stored in the core database

+

Each data resource can contain a value, which is any JSON type. String, number, +boolean, array or object. This value is stored directly in the FireFly database.

+

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

+

Datatype - validation of agreed data types

+

A datatype can be associated with your data, causing FireFly to verify the +value against a schema before accepting it (on upload, or receipt from another +party in the network).

+

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.

+
+

More information in the Datatype section

+
+

Blob - binary data stored via the Data Exchange

+

Data resources can also contain a blob 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.

+

A Data resource can contain both a value JSON payload, and a blob 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.

+

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 value, and it has a property +called name, then this value forms part of the data hash (as does every field +in the value) and is stored in a separately indexed blob.name field.

+

The upload REST API provides an autometa form field, which can be set to ask +FireFly core to automatically set the value to contain the filename, size, and +MIME type from the file upload.

+ + +

Example

+
{
+    "id": "4f11e022-01f4-4c3f-909f-5226947d9ef0",
+    "validator": "json",
+    "namespace": "ns1",
+    "hash": "5e2758423c99b799f53d3f04f587f5716c1ff19f1d1a050f40e02ea66860b491",
+    "created": "2022-05-16T01:23:15Z",
+    "datatype": {
+        "name": "widget",
+        "version": "v1.2.3"
+    },
+    "value": {
+        "name": "filename.pdf",
+        "a": "example",
+        "b": {
+            "c": 12345
+        }
+    },
+    "blob": {
+        "hash": "cef238f7b02803a799f040cdabe285ad5cd6db4a15cb9e2a1000f2860884c7ad",
+        "size": 12345,
+        "name": "filename.pdf"
+    }
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the data resourceUUID
validatorThe data validator typeFFEnum:
namespaceThe namespace of the data resourcestring
hashThe hash of the data resource. Derived from the value and the hash of any binary blob attachmentBytes32
createdThe creation time of the data resourceFFTime
datatypeThe optional datatype to use of validation of this dataDatatypeRef
valueThe 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 attachmentJSONAny
publicIf 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.)string
blobAn optional hash reference to a binary blob attachmentBlobRef
+

DatatypeRef

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
nameThe name of the datatypestring
versionThe version of the datatype. Semantic versioning is encouraged, such as v1.0.1string
+

BlobRef

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
hashThe hash of the binary blob dataBytes32
sizeThe size of the binary dataint64
nameThe name field from the metadata attached to the blob, commonly used as a path/filename, and indexed for searchstring
pathIf a name is specified, this field stores the '/' prefixed and separated path extracted from the full namestring
publicIf 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.)string
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/datatype/index.html b/v1.3.1/reference/types/datatype/index.html new file mode 100644 index 000000000..5fe29b800 --- /dev/null +++ b/v1.3.1/reference/types/datatype/index.html @@ -0,0 +1,3570 @@ + + + + + + + + + + + + + + + + + + + + + + + Datatype - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Datatype

+ + +

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.

+

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 message_rejected event +(rather than message_confirmed event).

+

Currently JSON Schema validation of data is supported.

+

The system for defining datatypes is pluggable, to support other schemes in the future, +such as XML Schema, or CSV, EDI etc.

+ + +

Example

+
{
+    "id": "3a479f7e-ddda-4bda-aa24-56d06c0bf08e",
+    "message": "bfcf904c-bdf7-40aa-bbd7-567f625c26c0",
+    "validator": "json",
+    "namespace": "ns1",
+    "name": "widget",
+    "version": "1.0.0",
+    "hash": "639cd98c893fa45a9df6fd87bd0393a9b39e31e26fbb1eeefe90cb40c3fa02d2",
+    "created": "2022-05-16T01:23:16Z",
+    "value": {
+        "$id": "https://example.com/widget.schema.json",
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "title": "Widget",
+        "type": "object",
+        "properties": {
+            "id": {
+                "type": "string",
+                "description": "The unique identifier for the widget."
+            },
+            "name": {
+                "type": "string",
+                "description": "The person's last name."
+            }
+        },
+        "additionalProperties": false
+    }
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the datatypeUUID
messageThe UUID of the broadcast message that was used to publish this datatype to the networkUUID
validatorThe validator that should be used to verify this datatypeFFEnum:
"json"
"none"
"definition"
namespaceThe namespace of the datatype. Data resources can only be created referencing datatypes in the same namespacestring
nameThe name of the datatypestring
versionThe version of the datatype. Multiple versions can exist with the same name. Use of semantic versioning is encourages, such as v1.0.1string
hashThe 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 datatypeBytes32
createdThe time the datatype was createdFFTime
valueThe definition of the datatype, in the syntax supported by the validator (such as a JSON Schema definition)JSONAny
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/event/index.html b/v1.3.1/reference/types/event/index.html new file mode 100644 index 000000000..6e38347c2 --- /dev/null +++ b/v1.3.1/reference/types/event/index.html @@ -0,0 +1,3837 @@ + + + + + + + + + + + + + + + + + + + + + + + Event - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Event

+ + +

Every Event emitted by FireFly shares a common structure.

+
+

See Events for a reference for how the overall event bus +in Hyperledger FireFly operates, and descriptions of all the sub-categories +of events.

+
+

Sequence

+

A local sequence 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.

+

Reference

+

Events have a reference to the UUID of an object that is the subject of the event, +such as a detailed Blockchain Event, or an off-chain +Message.

+

When events are delivered to your application, the reference field is +automatically retrieved and included in the JSON payload +that is delivered to your application.

+

You can use the ?fetchreferences query parameter on API calls to request the same +in-line JSON payload be included in query results.

+

The type of the reference also determines what subscription filters apply +when performing server-side filters.

+

Here is the mapping between event types, and the object that you find in +the reference field.

+

Correlator

+

For some event types, there is a secondary reference to an object that is +associated with the event. This is set in a correlator field on the +Event, but is not automatically fetched. This field is primarily used +for the confirm option on API calls to allow FireFly to determine +when a request has succeeded/failed.

+

Topic

+

Events have a topic, 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.

+

For example when you send a Message, you set the topics +you want that message to apply to, and FireFly ensures a consistent global +order between all parties that receive that message.

+

Transaction

+

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.

+

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

+

Note that some events cannot be tagged with a Transaction ID:

+
    +
  • Blockchain events, unless they were part of a batch-pin transaction + for transfer of a message
    • +
  • Token transfers/approvals, unless they had a message transfer associated + with them (and included a data payload in the event they emitted)
    • +
+

Reference, Topic and Correlator by Event Type

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypesReferenceTopicCorrelator
transaction_submittedTransactiontransaction.type
message_confirmed
message_rejected		Messagemessage.header.topics[i]*message.header.cid
token_pool_confirmedTokenPooltokenPool.id
token_pool_op_failedOperationtokenPool.idtokenPool.id
token_transfer_confirmedTokenTransfertokenPool.id
token_transfer_op_failedOperationtokenPool.idtokenTransfer.localId
token_approval_confirmedTokenApprovaltokenPool.id
token_approval_op_failedOperationtokenPool.idtokenApproval.localId
namespace_confirmedNamespace"ff_definition"
datatype_confirmedDatatype"ff_definition"
identity_confirmed
identity_updated		Identity"ff_definition"
contract_interface_confirmedFFI"ff_definition"
contract_api_confirmedContractAPI"ff_definition"
blockchain_event_receivedBlockchainEventFrom listener **
blockchain_invoke_op_succeededOperation
blockchain_invoke_op_failedOperation
blockchain_contract_deploy_op_succeededOperation
blockchain_contract_deploy_op_failedOperation
+
+
    +
  • A separate event is emitted for each topic associated with a Message.
    • +
+

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

+
+ + +

Example

+
{
+    "id": "5f875824-b36b-4559-9791-a57a2e2b30dd",
+    "sequence": 168,
+    "type": "transaction_submitted",
+    "namespace": "ns1",
+    "reference": "0d12aa75-5ed8-48a7-8b54-45274c6edcb1",
+    "tx": "0d12aa75-5ed8-48a7-8b54-45274c6edcb1",
+    "topic": "batch_pin",
+    "created": "2022-05-16T01:23:15Z"
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID assigned to this event by your local FireFly nodeUUID
sequenceA 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)int64
typeAll 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 applicationFFEnum:
"transaction_submitted"
"message_confirmed"
"message_rejected"
"datatype_confirmed"
"identity_confirmed"
"identity_updated"
"token_pool_confirmed"
"token_pool_op_failed"
"token_transfer_confirmed"
"token_transfer_op_failed"
"token_approval_confirmed"
"token_approval_op_failed"
"contract_interface_confirmed"
"contract_api_confirmed"
"blockchain_event_received"
"blockchain_invoke_op_succeeded"
"blockchain_invoke_op_failed"
"blockchain_contract_deploy_op_succeeded"
"blockchain_contract_deploy_op_failed"
namespaceThe namespace of the event. Your application must subscribe to events within a namespacestring
referenceThe 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 unsetUUID
correlatorFor 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 poolUUID
txThe UUID of a transaction that is event is part of. Not all events are part of a transactionUUID
topicA 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 typesstring
createdThe 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 applicationsFFTime
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/ffi/index.html b/v1.3.1/reference/types/ffi/index.html new file mode 100644 index 000000000..29f708486 --- /dev/null +++ b/v1.3.1/reference/types/ffi/index.html @@ -0,0 +1,3974 @@ + + + + + + + + + + + + + + + + + + + + + + + FFI - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

FFI

+ + +

See FireFly Interface Format

+ + +

Example

+
{
+    "id": "c35d3449-4f24-4676-8e64-91c9e46f06c4",
+    "message": "e4ad2077-5714-416e-81f9-7964a6223b6f",
+    "namespace": "ns1",
+    "name": "SimpleStorage",
+    "description": "A simple example contract in Solidity",
+    "version": "v0.0.1",
+    "methods": [
+        {
+            "id": "8f3289dd-3a19-4a9f-aab3-cb05289b013c",
+            "interface": "c35d3449-4f24-4676-8e64-91c9e46f06c4",
+            "name": "get",
+            "namespace": "ns1",
+            "pathname": "get",
+            "description": "Get the current value",
+            "params": [],
+            "returns": [
+                {
+                    "name": "output",
+                    "schema": {
+                        "type": "integer",
+                        "details": {
+                            "type": "uint256"
+                        }
+                    }
+                }
+            ],
+            "details": {
+                "stateMutability": "viewable"
+            }
+        },
+        {
+            "id": "fc6f54ee-2e3c-4e56-b17c-4a1a0ae7394b",
+            "interface": "c35d3449-4f24-4676-8e64-91c9e46f06c4",
+            "name": "set",
+            "namespace": "ns1",
+            "pathname": "set",
+            "description": "Set the value",
+            "params": [
+                {
+                    "name": "newValue",
+                    "schema": {
+                        "type": "integer",
+                        "details": {
+                            "type": "uint256"
+                        }
+                    }
+                }
+            ],
+            "returns": [],
+            "details": {
+                "stateMutability": "payable"
+            }
+        }
+    ],
+    "events": [
+        {
+            "id": "9f653f93-86f4-45bc-be75-d7f5888fbbc0",
+            "interface": "c35d3449-4f24-4676-8e64-91c9e46f06c4",
+            "namespace": "ns1",
+            "pathname": "Changed",
+            "signature": "Changed(address,uint256)",
+            "name": "Changed",
+            "description": "Emitted when the value changes",
+            "params": [
+                {
+                    "name": "_from",
+                    "schema": {
+                        "type": "string",
+                        "details": {
+                            "type": "address",
+                            "indexed": true
+                        }
+                    }
+                },
+                {
+                    "name": "_value",
+                    "schema": {
+                        "type": "integer",
+                        "details": {
+                            "type": "uint256"
+                        }
+                    }
+                }
+            ]
+        }
+    ],
+    "published": false
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the FireFly interface (FFI) smart contract definitionUUID
messageThe UUID of the broadcast message that was used to publish this FFI to the networkUUID
namespaceThe namespace of the FFIstring
nameThe name of the FFI - usually matching the smart contract namestring
networkNameThe published name of the FFI within the multiparty networkstring
descriptionA description of the smart contract this FFI representsstring
versionA version for the FFI - use of semantic versioning such as 'v1.0.1' is encouragedstring
methodsAn array of smart contract method definitionsFFIMethod[]
eventsAn array of smart contract event definitionsFFIEvent[]
errorsAn array of smart contract error definitionsFFIError[]
publishedIndicates if the FFI is published to other members of the multiparty networkbool
+

FFIMethod

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the FFI method definitionUUID
interfaceThe UUID of the FFI smart contract definition that this method is part ofUUID
nameThe name of the methodstring
namespaceThe namespace of the FFIstring
pathnameThe unique name allocated to this method within the FFI for use on URL paths. Supports contracts that have multiple method overrides with the same namestring
descriptionA description of the smart contract methodstring
paramsAn array of method parameter/argument definitionsFFIParam[]
returnsAn array of method return definitionsFFIParam[]
detailsAdditional blockchain specific fields about this method from the original smart contract. Used by the blockchain plugin and for documentation generation.JSONObject
+

FFIParam

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
nameThe name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contractstring
schemaFireFly 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 detailJSONAny
+

FFIEvent

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the FFI event definitionUUID
interfaceThe UUID of the FFI smart contract definition that this event is part ofUUID
namespaceThe namespace of the FFIstring
pathnameThe unique name allocated to this event within the FFI for use on URL paths. Supports contracts that have multiple event overrides with the same namestring
signatureThe stringified signature of the event, as computed by the blockchain pluginstring
nameThe name of the eventstring
descriptionA description of the smart contract eventstring
paramsAn array of event parameter/argument definitionsFFIParam[]
detailsAdditional blockchain specific fields about this event from the original smart contract. Used by the blockchain plugin and for documentation generation.JSONObject
+

FFIParam

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
nameThe name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contractstring
schemaFireFly 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 detailJSONAny
+

FFIError

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the FFI error definitionUUID
interfaceThe UUID of the FFI smart contract definition that this error is part ofUUID
namespaceThe namespace of the FFIstring
pathnameThe unique name allocated to this error within the FFI for use on URL pathsstring
signatureThe stringified signature of the error, as computed by the blockchain pluginstring
nameThe name of the errorstring
descriptionA description of the smart contract errorstring
paramsAn array of error parameter/argument definitionsFFIParam[]
+

FFIParam

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
nameThe name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contractstring
schemaFireFly 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 detailJSONAny
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/group/index.html b/v1.3.1/reference/types/group/index.html new file mode 100644 index 000000000..7399f41c5 --- /dev/null +++ b/v1.3.1/reference/types/group/index.html @@ -0,0 +1,3675 @@ + + + + + + + + + + + + + + + + + + + + + + + Group - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Group

+ + +

A privacy group is a list of identities that should receive a private communication.

+

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.

+

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.

+
+

The sender is included automatically in the group when members are +specified in-line, if it is omitted.

+
+

Group identity hash

+

The identifying hash for a group is determined as follows:

+
    +
  • All identities are resolved to their DID.
    • +
  • An organization name or identity UUID can be used on input
    • +
  • The UUID of the node that should receive the data for each participant is + determined (if not specified).
    • +
  • The first node found that is in the same identity hierarchy as the + participant identity, will be chosen.
    • +
  • The list of participants is ordered by DID, with de-duplication of + any identities.
    • +
  • The namespace, name, and members array are then serialized into + a JSON object, without whitespace.
    • +
  • A SHA256 hash of the JSON object is calculated
    • +
+

Private messaging architecture

+

The mechanism that keeps data private and ordered, without leaking data to the +blockchain, is summarized in the below diagram.

+

The key points are:

+
    +
  • Data is sent off-chain to all participants via the Data Exchange plugin
    • +
  • The Data Exchange is responsible for encryption and off-chain identity verification
    • +
  • Only parties that are involved in the privacy group receive the data
    • +
  • Other parties are only able to view the blockchain transaction
    • +
  • The hash and member list of the group are not shared outside of the privacy group
    • +
  • The name of the group can be used as an additional salt in generation of the group hash
    • +
  • 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
    • +
  • The blockchain transaction is the source of truth for ordering
    • +
  • 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)
    • +
  • 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
    • +
  • The ordering context (topic+group) is combined with a nonce that is incremented + for each individual sender, to form a message-specific hash.
    • +
  • 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)
    • +
+
+

See NextPin for more information on the structure used for storing the next +expected masked context pin, for each member of the privacy group.

+
+

FireFly Privacy Model

+ + +

Example

+
{
+    "namespace": "ns1",
+    "name": "",
+    "members": [
+        {
+            "identity": "did:firefly:org/1111",
+            "node": "4f563179-b4bd-4161-86e0-c2c1c0869c4f"
+        },
+        {
+            "identity": "did:firefly:org/2222",
+            "node": "61a99af8-c1f7-48ea-8fcc-489e4822a0ed"
+        }
+    ],
+    "localNamespace": "ns1",
+    "message": "0b9dfb76-103d-443d-92fd-b114fe07c54d",
+    "hash": "c52ad6c034cf5c7382d9a294f49297096a52eb55cc2da696c564b2a276633b95",
+    "created": "2022-05-16T01:23:16Z"
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
namespaceThe namespace of the group within the multiparty networkstring
nameThe optional name of the group, allowing multiple unique groups to exist with the same list of recipientsstring
membersThe list of members in this privacy groupMember[]
localNamespaceThe local namespace of the groupstring
messageThe message used to broadcast this group privately to the membersUUID
hashThe identifier hash of this group. Derived from the name and group membersBytes32
createdThe time when the group was first used to send a message in the networkFFTime
+

Member

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
identityThe DID of the group memberstring
nodeThe UUID of the node that receives a copy of the off-chain message for the identityUUID
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/identity/index.html b/v1.3.1/reference/types/identity/index.html new file mode 100644 index 000000000..0e4af33b7 --- /dev/null +++ b/v1.3.1/reference/types/identity/index.html @@ -0,0 +1,3658 @@ + + + + + + + + + + + + + + + + + + + + + + + Identity - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Identity

+ + +

FireFly contains an address book of identities, which is managed in a decentralized +way across a multi-party system through claim and verification system.

+
+

See FIR-12 for evolution +that is happening to Hyperledger FireFly to allow:

+
    +
  • Private address books that are not shared with other participants
    • +
  • Multiple address books backed by different chains, in the same node
    • +
+
+

Root identities are registered with only a claim - which is a signed +transaction from a particular blockchain account, to bind a DID with a +name that is unique within the network, to that signing key.

+

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.

+

When child identities are registered, a claim 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 verification that references +the claim (by UUID) using the key verifier of the parent identity.

+

DIDs

+

FireFly has adopted the DID standard for +representing identities. A "DID Method" name of firefly is used to represent +that the built-in identity system of Hyperledger FireFly is being used +to resolve these DIDs.

+

So an example FireFly DID for organization abcd1234 is:

+
    +
  • did:firefly:org/abcd1234
    • +
+
+

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.

+
+

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.

+ + +

Example

+
{
+    "id": "114f5857-9983-46fb-b1fc-8c8f0a20846c",
+    "did": "did:firefly:org/org_1",
+    "type": "org",
+    "parent": "688072c3-4fa0-436c-a86b-5d89673b8938",
+    "namespace": "ff_system",
+    "name": "org_1",
+    "messages": {
+        "claim": "911b364b-5863-4e49-a3f8-766dbbae7c4c",
+        "verification": "24636f11-c1f9-4bbb-9874-04dd24c7502f",
+        "update": null
+    },
+    "created": "2022-05-16T01:23:15Z"
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the identityUUID
didThe DID of the identity. Unique across namespaces within a FireFly networkstring
typeThe type of the identityFFEnum:
"org"
"node"
"custom"
parentThe UUID of the parent identity. Unset for root organization identitiesUUID
namespaceThe namespace of the identity. Organization and node identities are always defined in the ff_system namespacestring
nameThe name of the identity. The name must be unique within the type and namespacestring
descriptionA description of the identity. Part of the updatable profile information of an identitystring
profileA set of metadata for the identity. Part of the updatable profile information of an identityJSONObject
messagesReferences to the broadcast messages that established this identity and proved ownership of the associated verifiers (keys)IdentityMessages
createdThe creation time of the identityFFTime
updatedThe last update time of the identity profileFFTime
+

IdentityMessages

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
claimThe UUID of claim messageUUID
verificationThe UUID of claim message. Unset for root organization identitiesUUID
updateThe UUID of the most recently applied update message. Unset if no updates have been confirmedUUID
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/message/index.html b/v1.3.1/reference/types/message/index.html new file mode 100644 index 000000000..559163403 --- /dev/null +++ b/v1.3.1/reference/types/message/index.html @@ -0,0 +1,3928 @@ + + + + + + + + + + + + + + + + + + + + + + + Message - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Message

+ + +

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.

+

A message is made up of three sections:

+
    +
  1. The header - a set of metadata that determines how the message is ordered, who should receive it, and how they should process it
    2. +
  2. The data - an array of data attachments
    3. +
  3. Status information - fields that are calculated independently by each node, and hence update as the message makes it way through the system
    4. +
+

Hash

+

Sections (1) and (2) are fixed once the message is sent, and a hash is generated that provides tamper protection.

+

The hash is a function of the header, and all of the data payloads. Calculated as follows:

+
    +
  • The hash of each Data element is calculated individually
    • +
  • A JSON array of [{"id":"{{DATA_UUID}}","hash":"{{DATA_HASH}}"}] is hashed, and that hash is stored in header.datahash
    • +
  • The header is serialized as JSON with the deterministic order (listed below) and hashed
    • +
  • JSON data is serialized without whitespace to hash it.
    • +
  • The hashing algorithm is SHA-256
    • +
+

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.

+

Tag

+

The header.tag tells the processors of the message how it should be processed, and what data they should expect it to contain.

+

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

+

Every copy of the application that runs in the participants of the network should look at this tag to determine what +logic to execute against it.

+
+

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.

+
+

Topics

+

The header.topics 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 default topic is not recommended).

+

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.

+

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 & network links involved in that off-chain communication.

+

A "stop the world" approach to handling a single piece of missing data is not practical for a high volume +production business network.

+

The ordering context is a function of:

+
    +
  1. Whether the message is broadcast or private
    2. +
  2. If it is private, the privacy group associated with the message
    3. +
  3. The topic of the message
    4. +
+

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.

+

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.

+

For your application, you should choose the most granular identifier you can for your topic 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:

+
    +
  • A business transaction identifier - to ensure all data related to particular business transaction are processed in order
    • +
  • A globally agreed customer identifier - to ensure all data related to a particular business entity are processed in order
    • +
+

Using multiple topics

+

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.

+

A synchronization point between two otherwise independent streams of communication.

+

To do this, simply specify two topics in the message you sent, and the message will be independently ordered against +both of those topics.

+
+

You will also receive two events for the confirmation of that message, one for each topic.

+
+

Some examples:

+
    +
  • Agreeing to join two previously separate business transactions with ids 000001 and 000002, by discarding business transaction 000001 as a duplicate
    • +
  • Specify topics: ["000001","000002"] on the special merge message, and then from that point onwards you would only need to specify topics: ["000002"].
    • +
  • Agreeing to join two previously separate entities with id1 and id2, into a merged entity with id3.
    • +
  • Specify topics: ["id1","id2","id3"] on the special merge message, and then from that point onwards you would only need to specify topics: ["id3"].
    • +
+

Transaction type

+

By default messages are pinned to the blockchain, within a Batch.

+

For private messages, you can choose to disable this pinning by setting header.txtype: "unpinned".

+

Broadcast messages must be pinned to the blockchain.

+

In-line data

+

When sending a message you can specify the array of Data attachments in-line, as part of the same JSON payload.

+

For example, a minimal broadcast message could be:

+
{
+    "data": [
+        {"value": "hello world"}
+    ]
+}
+
+

When you send this message with /api/v1/namespaces/{ns}/messages/broadcast:

+
    +
  • The header will be initialized with the default values, including txtype: "batch_pin"
    • +
  • The data[0] entry will be stored as a Data resource
    • +
  • The message will be assembled into a batch and broadcast
    • +
+ + +

Example

+
{
+    "header": {
+        "id": "4ea27cce-a103-4187-b318-f7b20fd87bf3",
+        "cid": "00d20cba-76ed-431d-b9ff-f04b4cbee55c",
+        "type": "private",
+        "txtype": "batch_pin",
+        "author": "did:firefly:org/acme",
+        "key": "0xD53B0294B6a596D404809b1d51D1b4B3d1aD4945",
+        "created": "2022-05-16T01:23:10Z",
+        "namespace": "ns1",
+        "group": "781caa6738a604344ae86ee336ada1b48a404a85e7041cf75b864e50e3b14a22",
+        "topics": [
+            "topic1"
+        ],
+        "tag": "blue_message",
+        "datahash": "c07be180b147049baced0b6219d9ce7a84ab48f2ca7ca7ae949abb3fe6491b54"
+    },
+    "localNamespace": "ns1",
+    "state": "confirmed",
+    "confirmed": "2022-05-16T01:23:16Z",
+    "data": [
+        {
+            "id": "fdf9f118-eb81-4086-a63d-b06715b3bb4e",
+            "hash": "34cf848d896c83cdf433ea7bd9490c71800b316a96aac3c3a78a42a4c455d67d"
+        }
+    ]
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
headerThe message header contains all fields that are used to build the message hashMessageHeader
localNamespaceThe local namespace of the messagestring
hashThe hash of the message. Derived from the header, which includes the data hashBytes32
batchThe UUID of the batch in which the message was pinned/transferredUUID
txidThe ID of the transaction used to order/deliver this messageUUID
stateThe current state of the messageFFEnum:
"staged"
"ready"
"sent"
"pending"
"confirmed"
"rejected"
"cancelled"
confirmedThe timestamp of when the message was confirmed/rejectedFFTime
rejectReasonIf a message was rejected, provides details on the rejection reasonstring
dataThe list of data elements attached to the messageDataRef[]
pinsFor private messages, a unique pin hash:nonce is assigned for each topicstring[]
idempotencyKeyAn 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 networkIdempotencyKey
+

MessageHeader

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the message. Unique to each messageUUID
cidThe correlation ID of the message. Set this when a message is a response to another messageUUID
typeThe type of the messageFFEnum:
"definition"
"broadcast"
"private"
"groupinit"
"transfer_broadcast"
"transfer_private"
"approval_broadcast"
"approval_private"
txtypeThe type of transaction used to order/deliver this messageFFEnum:
"none"
"unpinned"
"batch_pin"
"network_action"
"token_pool"
"token_transfer"
"contract_deploy"
"contract_invoke"
"contract_invoke_pin"
"token_approval"
"data_publish"
authorThe DID of identity of the submitterstring
keyThe on-chain signing key used to sign the transactionstring
createdThe creation time of the messageFFTime
namespaceThe namespace of the message within the multiparty networkstring
topicsA message topic associates this message with an ordered stream of data. A custom topic should be assigned - using the default topic is discouragedstring[]
tagThe message tag indicates the purpose of the message to the applications that process itstring
datahashA single hash representing all data in the message. Derived from the array of data ids+hashes attached to this messageBytes32
txparentThe parent transaction that originally triggered this messageTransactionRef
+

TransactionRef

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
typeThe type of the FireFly transactionFFEnum:
idThe UUID of the FireFly transactionUUID
+

DataRef

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the referenced data resourceUUID
hashThe hash of the referenced dataBytes32
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/namespace/index.html b/v1.3.1/reference/types/namespace/index.html new file mode 100644 index 000000000..7ba8a09e4 --- /dev/null +++ b/v1.3.1/reference/types/namespace/index.html @@ -0,0 +1,3521 @@ + + + + + + + + + + + + + + + + + + + + + + + Namespace - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Namespace

+ + +

A namespace is a logical isolation domain for different applications, or tenants, that share the +FireFly node.

+
+

Significant evolution of the Hyperledger FireFly namespace construct, is proposed under +FIR-12

+
+ + +

Example

+
{
+    "name": "default",
+    "networkName": "default",
+    "description": "Default predefined namespace",
+    "created": "2022-05-16T01:23:16Z"
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
nameThe local namespace namestring
networkNameThe shared namespace name within the multiparty networkstring
descriptionA description of the namespacestring
createdThe time the namespace was createdFFTime
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/nextpin/index.html b/v1.3.1/reference/types/nextpin/index.html new file mode 100644 index 000000000..64e101768 --- /dev/null +++ b/v1.3.1/reference/types/nextpin/index.html @@ -0,0 +1,3528 @@ + + + + + + + + + + + + + + + + + + + + + + + NextPin - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

NextPin

+ + +

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.

+

This allows every member to maintain a global order of transactions within a topic in a privacy group, without +leaking the same hash between the messages that are communicated in that group.

+
+

See Group for more information on privacy groups.

+
+ + +

Example

+
{
+    "namespace": "ns1",
+    "context": "a25b65cfe49e5ed78c256e85cf07c96da938144f12fcb02fe4b5243a4631bd5e",
+    "identity": "did:firefly:org/example",
+    "hash": "00e55c63905a59782d5bc466093ead980afc4a2825eb68445bcf1312cc3d6de2",
+    "nonce": 12345
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
namespaceThe namespace of the next-pinstring
contextThe 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-chainBytes32
identityThe member of the privacy group the next-pin applies tostring
hashThe unique masked pin stringBytes32
nonceThe numeric index - which is monotonically increasing for each member of the privacy groupint64
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/operation/index.html b/v1.3.1/reference/types/operation/index.html new file mode 100644 index 000000000..2392eb12a --- /dev/null +++ b/v1.3.1/reference/types/operation/index.html @@ -0,0 +1,3595 @@ + + + + + + + + + + + + + + + + + + + + + + + Operation - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Operation

+ + +

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.

+

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.

+

FireFly operations by transaction type

+

Operation status

+

When initially created an operation is in Initialized state. Once the operation has been successfully sent to its respective plugin to be processed its +status moves to Pending state. This indicates that the plugin is processing the operation. The operation will then move to Succeeded or Failed +state depending on the outcome.

+

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 Initialized state. Re-submitting the same FireFly API call using the same idempotency key will cause FireFly +to re-submit the operation to its plugin.

+ + +

Example

+
{
+    "id": "04a8b0c4-03c2-4935-85a1-87d17cddc20a",
+    "namespace": "ns1",
+    "tx": "99543134-769b-42a8-8be4-a5f8873f969d",
+    "type": "sharedstorage_upload_batch",
+    "status": "Succeeded",
+    "plugin": "ipfs",
+    "input": {
+        "id": "80d89712-57f3-48fe-b085-a8cba6e0667d"
+    },
+    "output": {
+        "payloadRef": "QmWj3tr2aTHqnRYovhS2mQAjYneRtMWJSU4M4RdAJpJwEC"
+    },
+    "created": "2022-05-16T01:23:15Z"
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the operationUUID
namespaceThe namespace of the operationstring
txThe UUID of the FireFly transaction the operation is part ofUUID
typeThe type of the operationFFEnum:
"blockchain_pin_batch"
"blockchain_network_action"
"blockchain_deploy"
"blockchain_invoke"
"sharedstorage_upload_batch"
"sharedstorage_upload_blob"
"sharedstorage_upload_value"
"sharedstorage_download_batch"
"sharedstorage_download_blob"
"dataexchange_send_batch"
"dataexchange_send_blob"
"token_create_pool"
"token_activate_pool"
"token_transfer"
"token_approval"
statusThe current status of the operationOpStatus
pluginThe plugin responsible for performing the operationstring
inputThe input to this operationJSONObject
outputAny output reported back from the plugin for this operationJSONObject
errorAny error reported back from the plugin for this operationstring
createdThe time the operation was createdFFTime
updatedThe last update time of the operationFFTime
retryIf this operation was initiated as a retry to a previous operation, this field points to the UUID of the operation being retriedUUID
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/operationwithdetail/index.html b/v1.3.1/reference/types/operationwithdetail/index.html new file mode 100644 index 000000000..04e2e39db --- /dev/null +++ b/v1.3.1/reference/types/operationwithdetail/index.html @@ -0,0 +1,3663 @@ + + + + + + + + + + + + + + + + + + + + + + + OperationWithDetail - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

OperationWithDetail

+ + +

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 detail field.

+ + +

Example

+
{
+    "id": "04a8b0c4-03c2-4935-85a1-87d17cddc20a",
+    "namespace": "ns1",
+    "tx": "99543134-769b-42a8-8be4-a5f8873f969d",
+    "type": "sharedstorage_upload_batch",
+    "status": "Succeeded",
+    "plugin": "ipfs",
+    "input": {
+        "id": "80d89712-57f3-48fe-b085-a8cba6e0667d"
+    },
+    "output": {
+        "payloadRef": "QmWj3tr2aTHqnRYovhS2mQAjYneRtMWJSU4M4RdAJpJwEC"
+    },
+    "created": "2022-05-16T01:23:15Z",
+    "detail": {
+        "created": "2023-01-27T17:04:24.26406392Z",
+        "firstSubmit": "2023-01-27T17:04:24.419913295Z",
+        "gas": "4161076",
+        "gasPrice": "0",
+        "history": [
+            {
+                "actions": [
+                    {
+                        "action": "AssignNonce",
+                        "count": 1,
+                        "lastOccurrence": "",
+                        "time": ""
+                    },
+                    {
+                        "action": "RetrieveGasPrice",
+                        "count": 1,
+                        "lastOccurrence": "2023-01-27T17:11:41.161213303Z",
+                        "time": "2023-01-27T17:11:41.161213303Z"
+                    },
+                    {
+                        "action": "Submit",
+                        "count": 1,
+                        "lastOccurrence": "2023-01-27T17:11:41.222374636Z",
+                        "time": "2023-01-27T17:11:41.222374636Z"
+                    }
+                ],
+                "subStatus": "Received",
+                "time": "2023-01-27T17:11:41.122965803Z"
+            },
+            {
+                "actions": [
+                    {
+                        "action": "ReceiveReceipt",
+                        "count": 1,
+                        "lastOccurrence": "2023-01-27T17:11:47.930332625Z",
+                        "time": "2023-01-27T17:11:47.930332625Z"
+                    },
+                    {
+                        "action": "Confirm",
+                        "count": 1,
+                        "lastOccurrence": "2023-01-27T17:12:02.660275549Z",
+                        "time": "2023-01-27T17:12:02.660275549Z"
+                    }
+                ],
+                "subStatus": "Tracking",
+                "time": "2023-01-27T17:11:41.222400219Z"
+            },
+            {
+                "actions": [],
+                "subStatus": "Confirmed",
+                "time": "2023-01-27T17:12:02.660309382Z"
+            }
+        ],
+        "historySummary": [
+            {
+                "count": 1,
+                "subStatus": "Received"
+            },
+            {
+                "action": "AssignNonce",
+                "count": 1
+            },
+            {
+                "action": "RetrieveGasPrice",
+                "count": 1
+            },
+            {
+                "action": "Submit",
+                "count": 1
+            },
+            {
+                "count": 1,
+                "subStatus": "Tracking"
+            },
+            {
+                "action": "ReceiveReceipt",
+                "count": 1
+            },
+            {
+                "action": "Confirm",
+                "count": 1
+            },
+            {
+                "count": 1,
+                "subStatus": "Confirmed"
+            }
+        ],
+        "sequenceId": "0185f42f-fec8-93df-aeba-387417d477e0",
+        "status": "Succeeded",
+        "transactionHash": "0xfb39178fee8e725c03647b8286e6f5cb13f982abf685479a9ee59e8e9d9e51d8"
+    }
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the operationUUID
namespaceThe namespace of the operationstring
txThe UUID of the FireFly transaction the operation is part ofUUID
typeThe type of the operationFFEnum:
"blockchain_pin_batch"
"blockchain_network_action"
"blockchain_deploy"
"blockchain_invoke"
"sharedstorage_upload_batch"
"sharedstorage_upload_blob"
"sharedstorage_upload_value"
"sharedstorage_download_batch"
"sharedstorage_download_blob"
"dataexchange_send_batch"
"dataexchange_send_blob"
"token_create_pool"
"token_activate_pool"
"token_transfer"
"token_approval"
statusThe current status of the operationOpStatus
pluginThe plugin responsible for performing the operationstring
inputThe input to this operationJSONObject
outputAny output reported back from the plugin for this operationJSONObject
errorAny error reported back from the plugin for this operationstring
createdThe time the operation was createdFFTime
updatedThe last update time of the operationFFTime
retryIf this operation was initiated as a retry to a previous operation, this field points to the UUID of the operation being retriedUUID
detailAdditional detailed information about an operation provided by the connector``
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/simpletypes/index.html b/v1.3.1/reference/types/simpletypes/index.html new file mode 100644 index 000000000..7d41a13e8 --- /dev/null +++ b/v1.3.1/reference/types/simpletypes/index.html @@ -0,0 +1,3564 @@ + + + + + + + + + + + + + + + + + + + + + + + Simple Types - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Simple Types

+ +

UUID

+ +

IDs are generated as UUID V4 globally unique identifiers

+ + +

FFTime

+ +

Times are serialized to JSON on the API in RFC 3339 / ISO 8601 nanosecond UTC time +for example 2022-05-05T21:19:27.454767543Z.

+

Note that JavaScript can parse this format happily into millisecond time with Date.parse().

+

Times are persisted as a nanosecond resolution timestamps in the database.

+

On input, and in queries, times can be parsed from RFC3339, or unix timestamps +(second, millisecond or nanosecond resolution).

+ + +

FFBigInt

+ +

Large integers of up to 256bits in size are common in blockchain, and +handled in FireFly.

+

In JSON output payloads in FireFly, including events, they are serialized as +strings (with base 10).

+

On input you can provide JSON string (string with an 0x prefix are +parsed at base 16), or a JSON number.

+

Be careful when using JSON numbers, that the largest +number that is safe to transfer using a JSON number is 2^53 - 1.

+ + +

JSONAny

+ +

Any JSON type. An object, array, string, number, boolean or null.

+

FireFly stores object data with the same field order as was provided on the input, +but with any whitespace removed.

+ + +

JSONObject

+ +

Any JSON Object. Must be an object, rather than an array or a simple type.

+ + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/subscription/index.html b/v1.3.1/reference/types/subscription/index.html new file mode 100644 index 000000000..aa45a8b38 --- /dev/null +++ b/v1.3.1/reference/types/subscription/index.html @@ -0,0 +1,4291 @@ + + + + + + + + + + + + + + + + + + + + + + + Subscription - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Subscription

+ + +

Each Subscription tracks delivery of events to a particular +application, and allows FireFly to ensure that messages are delivered reliably +to that application.

+

FireFly Event Subscription Model

+

Creating a subscription

+

Before you can connect to a subscription, you must create it via the REST API.

+
+

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.

+
+

When creating a new subscription, you give it a name which is how you will +refer to it when you connect.

+

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.

+

All subscriptions are created within a namespace, and automatically filter +events to only those emitted within that namespace.

+

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.

+

Subscriptions and workload balancing

+

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.

+
+

Each event is only delivered once to the subscription, regardless of how +many instances of your application connect to FireFly.

+
+

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.

+

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.

+

Pluggable Transports

+

Hyperledger FireFly has two built-in transports for delivery of events +to applications - WebSockets and Webhooks.

+

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.

+

WebSockets

+

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.

+
+

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.

+

A Java SDK is a roadmap item for the community.

+
+

WebSocket protocol

+

FireFly has a simple protocol on top of WebSockets:

+
    +
  1. 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):
    2. +
  2. Send a WSStart JSON payload
    3. +
  3. Include a namespace and name query parameter in the URL when you + connect, along with query params for other fields of WSStart
    4. +
  4. One you have started your subscription, each event flows from + the server, to your application as a JSON Event payload
    5. +
  5. For each event you receive, you need to send a WSAck payload.
    6. +
  6. Unless you specified autoack in step (1)
    7. +
+
+

The SDK libraries for FireFly help you ensure you send the start +payload each time your WebSocket reconnects.

+
+

Using start and ack explicitly

+

Here's an example websocat command +showing an explicit start and ack.

+
$ websocat ws://localhost:5000/ws
+{"type":"start","namespace":"default","name":"docexample"}
+# ... for each event that arrives here, you send an ack ...
+{"type":"ack","id":"70ed4411-57cf-4ba1-bedb-fe3b4b5fd6b6"}
+
+

When creating your subscription, you can set readahead in order to +ask FireFly to stream a number of messages to your application, +ahead of receiving the acknowledgements.

+
+

readahead 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 ack for each event.

+
+

Auto-starting via URL query and autoack

+

Here's an example websocat where we use +URL query parameters to avoid the need to send a start JSON payload.

+

We also use autoack so that events just keep flowing from the server.

+
$ websocat "ws://localhost:5000/ws?namespace=default&name=docexample&autoack"
+# ... events just keep arriving here, as the server-side auto-acknowledges
+#     the events as it delivers them to you.
+
+
+

Note using autoack 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.

+
+

Ephemeral WebSocket subscriptions

+

FireFly WebSockets provide a special option to create a subscription dynamically, that +only lasts for as long as you are connected to the server.

+

We call these ephemeral subscriptions.

+

Here's an example websocat command +showing an an ephemeral subscription - notice we don't specify a name for the +subscription, and there is no need to have already created the subscription +beforehand.

+

Here we also include an extra query parameter to set a server-side filter, to only +include message events.

+
$ websocat "ws://localhost:5000/ws?namespace=default&ephemeral&autoack&filter.events=message_.*"
+{"type":"start","namespace":"default","name":"docexample"}
+# ... for each event that arrives here, you send an ack ...
+{"type":"ack","id":"70ed4411-57cf-4ba1-bedb-fe3b4b5fd6b6"}
+
+
+

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.

+
+

Webhooks

+

The Webhook transport allows FireFly to make HTTP calls against your application's API +when events matching your subscription are emitted.

+

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.

+
+

Webhooks are great for serverless functions (AWS Lambda etc.), integrations +with SaaS applications, and calling existing APIs.

+
+

The FireFly configuration options for a Webhook subscription are very flexible, +allowing you to customize your HTTP requests as follows:

+
    +
  • Set the HTTP request details:
    • +
  • Method, URL, query, headers and input body
    • +
  • Wait for a invocation of the back-end service, before acknowledging
    • +
  • To retry requests to your Webhook on a non-2xx HTTP status code + or other error, you should enable and configure + options.retry
    • +
  • The event is acknowledged once the request (with any retries), is + completed - regardless of whether the outcome was a success or failure.
    • +
  • Use fastack to acknowledge against FireFly immediately and make multiple + parallel calls to the HTTP API in a fire-and-forget fashion.
    • +
  • Set the HTTP request details dynamically from message_confirmed events:
    • +
  • Map data out of the first data element in message events
    • +
  • Requires withData to be set on the subscription, in addition to the + input.* configuration options
    • +
  • Can automatically generate a "reply" message for message_confirmed events:
    • +
  • Maps the response body of the HTTP call to data in the reply message
    • +
  • Sets the cid and topic in the reply message to match the request
    • +
  • Sets a tag in the reply message, per the configuration, or dynamically + based on a field in the input request data.
    • +
+

Batching events

+

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 readAhead limit and an optional timeout can be specified to send the events when the batch hasn't filled.

+

To enable this set the following configuration under SubscriptionOptions

+

batch | 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. | bool |

+

batchTimeout | When batching is enabled, the optional timeout to send events even when the batch hasn't filled. Defaults to 2 seconds | string

+

NOTE: When batch is enabled, withData 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.

+ + +

Example

+
{
+    "id": "c38d69fd-442e-4d6f-b5a4-bab1411c7fe8",
+    "namespace": "ns1",
+    "name": "app1",
+    "transport": "websockets",
+    "filter": {
+        "events": "^(message_.*|token_.*)$",
+        "message": {
+            "tag": "^(red|blue)$"
+        },
+        "transaction": {},
+        "blockchainevent": {}
+    },
+    "options": {
+        "firstEvent": "newest",
+        "readAhead": 50
+    },
+    "created": "2022-05-16T01:23:15Z",
+    "updated": null
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the subscriptionUUID
namespaceThe namespace of the subscription. A subscription will only receive events generated in the namespace of the subscriptionstring
nameThe 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 instancesstring
transportThe transport plugin responsible for event delivery (WebSockets, Webhooks, JMS, NATS etc.)string
filterServer-side filter to apply to eventsSubscriptionFilter
optionsSubscription optionsSubscriptionOptions
ephemeralEphemeral 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 connectionbool
createdCreation time of the subscriptionFFTime
updatedLast time the subscription was updatedFFTime
+

SubscriptionFilter

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
eventsRegular expression to apply to the event type, to subscribe to a subset of event typesstring
messageFilters specific to message events. If an event is not a message event, these filters are ignoredMessageFilter
transactionFilters specific to events with a transaction. If an event is not associated with a transaction, this filter is ignoredTransactionFilter
blockchaineventFilters specific to blockchain events. If an event is not a blockchain event, these filters are ignoredBlockchainEventFilter
topicRegular 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 topicstring
topicsDeprecated: Please use 'topic' insteadstring
tagDeprecated: Please use 'message.tag' insteadstring
groupDeprecated: Please use 'message.group' insteadstring
authorDeprecated: Please use 'message.author' insteadstring
+

MessageFilter

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
tagRegular expression to apply to the message 'header.tag' fieldstring
groupRegular expression to apply to the message 'header.group' fieldstring
authorRegular expression to apply to the message 'header.author' fieldstring
+

TransactionFilter

+ + + + + + + + + + + + + + + +
Field NameDescriptionType
typeRegular expression to apply to the transaction 'type' fieldstring
+

BlockchainEventFilter

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
nameRegular expression to apply to the blockchain event 'name' field, which is the name of the event in the underlying blockchain smart contractstring
listenerRegular 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 subscriptionsstring
+

SubscriptionOptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
firstEventWhether 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'SubOptsFirstEvent
readAheadThe 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 restartsuint16
withDataWhether 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.bool
batchEvents 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.bool
batchTimeoutWhen batching is enabled, the optional timeout to send events even when the batch hasn't filled.string
fastackWebhooks only: When true the event will be acknowledged before the webhook is invoked, allowing parallel invocationsbool
urlWebhooks only: HTTP url to invoke. Can be relative if a base URL is set in the webhook plugin configstring
methodWebhooks only: HTTP method to invoke. Default=POSTstring
jsonWebhooks only: Whether to assume the response body is JSON, regardless of the returned Content-Typebool
replyWebhooks only: Whether to automatically send a reply event, using the body returned by the webhookbool
replytagWebhooks only: The tag to set on the reply messagestring
replytxWebhooks only: The transaction type to set on the reply messagestring
headersWebhooks only: Static headers to set on the webhook request``
queryWebhooks only: Static query params to set on the webhook request``
tlsConfigNameThe name of an existing TLS configuration associated to the namespace to usestring
inputWebhooks only: A set of options to extract data from the first JSON input data in the incoming message. Only applies if withData=trueWebhookInputOptions
retryWebhooks only: a set of options for retrying the webhook callWebhookRetryOptions
httpOptionsWebhooks only: a set of options for HTTPWebhookHTTPOptions
+

WebhookInputOptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
queryA top-level property of the first data input, to use for query parametersstring
headersA top-level property of the first data input, to use for headersstring
bodyA top-level property of the first data input, to use for the request body. Default is the whole first bodystring
pathA top-level property of the first data input, to use for a path to append with escaping to the webhook pathstring
replytxA top-level property of the first data input, to use to dynamically set whether to pin the response (so the requester can choose)string
+

WebhookRetryOptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
enabledEnables retry on HTTP calls, defaults to falsebool
countNumber of times to retry the webhook call in case of failureint
initialDelayInitial delay between retries when we retry the webhook callstring
maxDelayMax delay between retries when we retry the webhookcallstring
+

WebhookHTTPOptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
proxyURLHTTP proxy URL to use for outbound requests to the webhookstring
tlsHandshakeTimeoutThe max duration to hold a TLS handshake alivestring
requestTimeoutThe max duration to hold a TLS handshake alivestring
maxIdleConnsThe max number of idle connections to hold pooledint
idleTimeoutThe max duration to hold a HTTP keepalive connection between callsstring
connectionTimeoutThe maximum amount of time that a connection is allowed to remain with no data transmitted.string
expectContinueTimeoutSee ExpectContinueTimeout in the Go docsstring
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/tokenapproval/index.html b/v1.3.1/reference/types/tokenapproval/index.html new file mode 100644 index 000000000..efb798bdd --- /dev/null +++ b/v1.3.1/reference/types/tokenapproval/index.html @@ -0,0 +1,3652 @@ + + + + + + + + + + + + + + + + + + + + + + + TokenApproval - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

TokenApproval

+ + +

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.

+

The approved "operator" (or "spender") account might be a smart contract, +or another individual.

+

FireFly provides APIs for initiating and tracking approvals, which token +connectors integrate with the implementation of the underlying token.

+

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 subject field, combined with the active 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 +"active": false, and the new approval is marked with "active": true

+
+

The token connector is responsible for the format of the subject field +to reflect the owner / operator (spender) relationship.

+
+ + +

Example

+
{
+    "localId": "1cd3e2e2-dd6a-441d-94c5-02439de9897b",
+    "pool": "1244ecbe-5862-41c3-99ec-4666a18b9dd5",
+    "connector": "erc20_erc721",
+    "key": "0x55860105d6a675dbe6e4d83f67b834377ba677ad",
+    "operator": "0x30017fd084715e41aa6536ab777a8f3a2b11a5a1",
+    "approved": true,
+    "info": {
+        "owner": "0x55860105d6a675dbe6e4d83f67b834377ba677ad",
+        "spender": "0x30017fd084715e41aa6536ab777a8f3a2b11a5a1",
+        "value": "115792089237316195423570985008687907853269984665640564039457584007913129639935"
+    },
+    "namespace": "ns1",
+    "protocolId": "000000000032/000000/000000",
+    "subject": "0x55860105d6a675dbe6e4d83f67b834377ba677ad:0x30017fd084715e41aa6536ab777a8f3a2b11a5a1",
+    "active": true,
+    "created": "2022-05-16T01:23:15Z",
+    "tx": {
+        "type": "token_approval",
+        "id": "4b6e086d-0e31-482d-9683-cd18b2045031"
+    }
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
localIdThe UUID of this token approval, in the local FireFly nodeUUID
poolThe UUID the token pool this approval applies toUUID
connectorThe name of the token connector, as specified in the FireFly core configuration file. Required on input when there are more than one token connectors configuredstring
keyThe blockchain signing key for the approval request. On input defaults to the first signing key of the organization that operates the nodestring
operatorThe blockchain identity that is granted the approvalstring
approvedWhether this record grants permission for an operator to perform actions on the token balance (true), or revokes permission (false)bool
infoToken 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 detailsJSONObject
namespaceThe namespace for the approval, which must match the namespace of the token poolstring
protocolIdAn alphanumerically sortable string that represents this event uniquely with respect to the blockchainstring
subjectA string identifying the parties and entities in the scope of this approval, as provided by the token connectorstring
activeIndicates if this approval is currently active (only one approval can be active per subject)bool
messageThe UUID of a message that has been correlated with this approval using the data field of the approval in a compatible token connectorUUID
messageHashThe hash of a message that has been correlated with this approval using the data field of the approval in a compatible token connectorBytes32
createdThe creation time of the token approvalFFTime
txIf submitted via FireFly, this will reference the UUID of the FireFly transaction (if the token connector in use supports attaching data)TransactionRef
blockchainEventThe UUID of the blockchain eventUUID
configInput only field, with token connector specific configuration of the approval. See your chosen token connector documentation for detailsJSONObject
+

TransactionRef

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
typeThe type of the FireFly transactionFFEnum:
idThe UUID of the FireFly transactionUUID
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/tokenpool/index.html b/v1.3.1/reference/types/tokenpool/index.html new file mode 100644 index 000000000..19d674f08 --- /dev/null +++ b/v1.3.1/reference/types/tokenpool/index.html @@ -0,0 +1,3743 @@ + + + + + + + + + + + + + + + + + + + + + + + TokenPool - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

TokenPool

+ + +

Token pools are a FireFly construct for describing a set of tokens.

+

The total supply of a particular fungible token, or a group of related non-fungible tokens.

+

The exact definition of a token pool is dependent on the token connector implementation.

+

Check the documentation for your chosen connector implementation to see the detailed options +for configuring a new Token Pool.

+

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.

+

Example token pool types

+

Some examples of how the generic concept of a Token Pool maps to various well-defined Ethereum standards:

+
    +
  • ERC-1155: a single contract instance can efficiently allocate + many isolated pools of fungible or non-fungible tokens
    • +
  • ERC-20 / ERC-777: + each contract instance represents a single fungible pool of value, e.g. "a coin"
    • +
  • ERC-721: each contract instance represents a single pool of NFTs, + each with unique identities within the pool
    • +
  • ERC-1400 / ERC-1410: + partially supported in the same manner as ERC-20/ERC-777, but would require new features for working with partitions
    • +
+

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.

+ + + + +

Example

+
{
+    "id": "90ebefdf-4230-48a5-9d07-c59751545859",
+    "type": "fungible",
+    "namespace": "ns1",
+    "name": "my_token",
+    "standard": "ERC-20",
+    "locator": "address=0x056df1c53c3c00b0e13d37543f46930b42f71db0\u0026schema=ERC20WithData\u0026type=fungible",
+    "decimals": 18,
+    "connector": "erc20_erc721",
+    "message": "43923040-b1e5-4164-aa20-47636c7177ee",
+    "active": true,
+    "created": "2022-05-16T01:23:15Z",
+    "info": {
+        "address": "0x056df1c53c3c00b0e13d37543f46930b42f71db0",
+        "name": "pool8197",
+        "schema": "ERC20WithData"
+    },
+    "tx": {
+        "type": "token_pool",
+        "id": "a23ffc87-81a2-4cbc-97d6-f53d320c36cd"
+    },
+    "published": false
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the token poolUUID
typeThe type of token the pool contains, such as fungible/non-fungibleFFEnum:
"fungible"
"nonfungible"
namespaceThe namespace for the token poolstring
nameThe name of the token pool. Note the name is not validated against the description of the token on the blockchainstring
networkNameThe published name of the token pool within the multiparty networkstring
standardThe ERC standard the token pool conforms to, as reported by the token connectorstring
locatorA unique identifier for the pool, as provided by the token connectorstring
keyThe 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-chainstring
symbolThe token symbol. If supplied on input for an existing on-chain token, this must match the on-chain informationstring
decimalsNumber of decimal places that this token hasint
connectorThe 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 configuredstring
messageThe UUID of the broadcast message used to inform the network about this poolUUID
activeIndicates whether the pool has been successfully activated with the token connectorbool
createdThe creation time of the poolFFTime
configInput 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 detailsJSONObject
infoToken connector specific information about the pool. See your chosen token connector documentation for detailsJSONObject
txReference to the FireFly transaction used to create and broadcast this pool to the networkTransactionRef
interfaceA reference to an existing FFI, containing pre-registered type information for the token contractFFIReference
interfaceFormatThe interface encoding format supported by the connector for this token poolFFEnum:
"abi"
"ffi"
methodsThe method definitions resolved by the token connector to be used by each token operationJSONAny
publishedIndicates if the token pool is published to other members of the multiparty networkbool
+

TransactionRef

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
typeThe type of the FireFly transactionFFEnum:
idThe UUID of the FireFly transactionUUID
+

FFIReference

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the FireFly interfaceUUID
nameThe name of the FireFly interfacestring
versionThe version of the FireFly interfacestring
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/tokentransfer/index.html b/v1.3.1/reference/types/tokentransfer/index.html new file mode 100644 index 000000000..f10fff084 --- /dev/null +++ b/v1.3.1/reference/types/tokentransfer/index.html @@ -0,0 +1,3735 @@ + + + + + + + + + + + + + + + + + + + + + + + TokenTransfer - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

TokenTransfer

+ + +

A Token Transfer is created for each transfer of value that happens under a token pool.

+

The transfers form an off-chain audit history (an "index") of the transactions that +have been performed on the blockchain.

+

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.

+

Hyperledger FireFly maintains this index automatically for all Token Pools that are configured.

+

FireFly initiated vs. non-FireFly initiated transfers

+

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.

+

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.

+

Message coordinated transfers

+

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.

+

These transfers have a message associated with them, and require a compatible Token Connector and +on-chain Smart Contract that allows a data payload to be included as part of the transfer, and to +be emitted as part of the transfer event.

+

Examples of how to do this are included in the ERC-20, ERC-721 and ERC-1155 Token Connector sample +smart contracts.

+

Transfer types

+

There are three primary types of transfer:

+
    +
  1. Mint - new tokens come into existence, increasing the total supply of tokens + within the pool. The from address will be unset for these transfer types.
    2. +
  2. Burn - existing tokens are taken out of circulation. The to address will be + unset for these transfer types.
    3. +
  3. Transfer - tokens move from ownership by one account, to another account. + The from and to addresses are both set for these type of transfers.
    4. +
+

Note that the key that signed the Transfer transaction might be different to the from +account that is the owner of the tokens before the transfer.

+

The Approval resource is used to track which signing accounts (other than the owner) +have approval to transfer tokens on the owner's behalf.

+ + +

Example

+
{
+    "type": "transfer",
+    "pool": "1244ecbe-5862-41c3-99ec-4666a18b9dd5",
+    "uri": "firefly://token/1",
+    "connector": "erc20_erc721",
+    "namespace": "ns1",
+    "key": "0x55860105D6A675dBE6e4d83F67b834377Ba677AD",
+    "from": "0x55860105D6A675dBE6e4d83F67b834377Ba677AD",
+    "to": "0x55860105D6A675dBE6e4d83F67b834377Ba677AD",
+    "amount": "1000000000000000000",
+    "protocolId": "000000000041/000000/000000",
+    "message": "780b9b90-e3b0-4510-afac-b4b1f2940b36",
+    "messageHash": "780204e634364c42779920eddc8d9fecccb33e3607eeac9f53abd1b31184ae4e",
+    "created": "2022-05-16T01:23:15Z",
+    "tx": {
+        "type": "token_transfer",
+        "id": "62767ca8-99f9-439c-9deb-d80c6672c158"
+    },
+    "blockchainEvent": "b57fcaa2-156e-4c3f-9b0b-ddec9ee25933"
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
typeThe type of transfer such as mint/burn/transferFFEnum:
"mint"
"burn"
"transfer"
localIdThe UUID of this token transfer, in the local FireFly nodeUUID
poolThe UUID the token pool this transfer applies toUUID
tokenIndexThe index of the token within the pool that this transfer applies tostring
uriThe URI of the token this transfer applies tostring
connectorThe name of the token connector, as specified in the FireFly core configuration file. Required on input when there are more than one token connectors configuredstring
namespaceThe namespace for the transfer, which must match the namespace of the token poolstring
keyThe blockchain signing key for the transfer. On input defaults to the first signing key of the organization that operates the nodestring
fromThe source account for the transfer. On input defaults to the value of 'key'string
toThe target account for the transfer. On input defaults to the value of 'key'string
amountThe 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,000FFBigInt
protocolIdAn alphanumerically sortable string that represents this event uniquely with respect to the blockchainstring
messageThe UUID of a message that has been correlated with this transfer using the data field of the transfer in a compatible token connectorUUID
messageHashThe hash of a message that has been correlated with this transfer using the data field of the transfer in a compatible token connectorBytes32
createdThe creation time of the transferFFTime
txIf submitted via FireFly, this will reference the UUID of the FireFly transaction (if the token connector in use supports attaching data)TransactionRef
blockchainEventThe UUID of the blockchain eventUUID
configInput only field, with token connector specific configuration of the transfer. See your chosen token connector documentation for detailsJSONObject
+

TransactionRef

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
typeThe type of the FireFly transactionFFEnum:
idThe UUID of the FireFly transactionUUID
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/transaction/index.html b/v1.3.1/reference/types/transaction/index.html new file mode 100644 index 000000000..341ecdace --- /dev/null +++ b/v1.3.1/reference/types/transaction/index.html @@ -0,0 +1,3557 @@ + + + + + + + + + + + + + + + + + + + + + + + Transaction - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Transaction

+ + +

FireFly Transactions are a grouping construct for a number of Operations and Events +that need to complete or fail as unit.

+
+

FireFly Transactions are not themselves Blockchain transactions, but in many cases there is +exactly one Blockchain transaction associated with each FireFly transaction. Exceptions include +unpinned transactions, where there is no blockchain transaction at all.

+
+

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.

+

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.

+

So there is a Blockchain ID 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 Blockchain Event Received event for the detection +of the event from the blockchain smart contract when the transaction was mined, and a Message Confirmed +event for each message in the batch (in this case 1). Then here the message was a special Definition message +that advertised a new Contract API to all members of the network - so there is a Contract API Confirmed +event as well.

+

FireFly Transactions - Explorer View

+

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.

+

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.

+ + +

Example

+
{
+    "id": "4e7e0943-4230-4f67-89b6-181adf471edc",
+    "namespace": "ns1",
+    "type": "contract_invoke",
+    "created": "2022-05-16T01:23:15Z",
+    "blockchainIds": [
+        "0x34b0327567fefed09ac7b4429549bc609302b08a9cbd8f019a078ec44447593d"
+    ]
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the FireFly transactionUUID
namespaceThe namespace of the FireFly transactionstring
typeThe type of the FireFly transactionFFEnum:
"none"
"unpinned"
"batch_pin"
"network_action"
"token_pool"
"token_transfer"
"contract_deploy"
"contract_invoke"
"contract_invoke_pin"
"token_approval"
"data_publish"
createdThe time the transaction was created on this node. Note the transaction is individually created with the same UUID on each participant in the FireFly transactionFFTime
idempotencyKeyAn optional unique identifier for a transaction. Cannot be duplicated within a namespace, thus allowing idempotent submission of transactions to the APIIdempotencyKey
blockchainIdsThe 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 transactionsstring[]
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/verifier/index.html b/v1.3.1/reference/types/verifier/index.html new file mode 100644 index 000000000..b2c5e2bfd --- /dev/null +++ b/v1.3.1/reference/types/verifier/index.html @@ -0,0 +1,3537 @@ + + + + + + + + + + + + + + + + + + + + + + + Verifier - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Verifier

+ + +

A verifier is a cryptographic verification mechanism for an identity in FireFly.

+

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.

+

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.

+
    +
  • Ethereum blockchains: The Ethereum address hex string
    • +
  • Hyperledger Fabric: The fully qualified MSP Identifier string
    • +
  • Data exchange: The data exchange "Peer ID", as determined by the DX plugin
    • +
+ + +

Example

+
{
+    "hash": "6818c41093590b862b781082d4df5d4abda6d2a4b71d737779edf6d2375d810b",
+    "identity": "114f5857-9983-46fb-b1fc-8c8f0a20846c",
+    "type": "ethereum_address",
+    "value": "0x30017fd084715e41aa6536ab777a8f3a2b11a5a1",
+    "created": "2022-05-16T01:23:15Z"
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
hashHash used as a globally consistent identifier for this namespace + type + value combination on every node in the networkBytes32
identityThe UUID of the parent identity that has claimed this verifierUUID
namespaceThe namespace of the verifierstring
typeThe type of the verifierFFEnum:
"ethereum_address"
"tezos_address"
"fabric_msp_id"
"dx_peer_id"
valueThe verifier string, such as an Ethereum address, or Fabric MSP identifierstring
createdThe time this verifier was created on this nodeFFTime
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/wsack/index.html b/v1.3.1/reference/types/wsack/index.html new file mode 100644 index 000000000..aed0b7d1e --- /dev/null +++ b/v1.3.1/reference/types/wsack/index.html @@ -0,0 +1,3569 @@ + + + + + + + + + + + + + + + + + + + + + + + WSAck - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

WSAck

+ + +

An ack must be sent on a WebSocket for each event delivered to an application.

+
+

Unless autoack is set in the WSStart payload/URL parameters to cause +automatic acknowledgement.

+
+

Your application should specify the id of each event that it acknowledges.

+

If the id is omitted, then FireFly will assume the oldest message delivered to the +application that has not been acknowledged is the one the ack is associated with.

+

If multiple subscriptions are started on a WebSocket, then you need to specify the +subscription namespace+name as part of each ack.

+

If you send an acknowledgement that cannot be correlated, then a WSError +payload will be sent to the application.

+ + +

Example

+
{
+    "type": "ack",
+    "id": "f78bf82b-1292-4c86-8a08-e53d855f1a64",
+    "subscription": {
+        "namespace": "ns1",
+        "name": "app1_subscription"
+    }
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
typeWSActionBase.typeFFEnum:
"start"
"ack"
"protocol_error"
"event_batch"
idWSAck.idUUID
subscriptionWSAck.subscriptionSubscriptionRef
+

SubscriptionRef

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
idThe UUID of the subscriptionUUID
namespaceThe namespace of the subscription. A subscription will only receive events generated in the namespace of the subscriptionstring
nameThe 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 instancesstring
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/wserror/index.html b/v1.3.1/reference/types/wserror/index.html new file mode 100644 index 000000000..999c4b4ad --- /dev/null +++ b/v1.3.1/reference/types/wserror/index.html @@ -0,0 +1,3504 @@ + + + + + + + + + + + + + + + + + + + + + + + WSError - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

WSError

+ + + + + +

Example

+
{
+    "type": "protocol_error",
+    "error": "FF10175: Acknowledgment does not match an inflight event + subscription"
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
typeWSAck.typeFFEnum:
"start"
"ack"
"protocol_error"
"event_batch"
errorWSAck.errorstring
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/reference/types/wsstart/index.html b/v1.3.1/reference/types/wsstart/index.html new file mode 100644 index 000000000..0054ab3ba --- /dev/null +++ b/v1.3.1/reference/types/wsstart/index.html @@ -0,0 +1,4029 @@ + + + + + + + + + + + + + + + + + + + + + + + WSStart - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

WSStart

+ + +

The start payload is sent after an application connects to a WebSocket, to start +delivery of events over that connection.

+

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.

+

Alternatively the start command can request "ephemeral": true in order to dynamically create a new +subscription that lasts only for the duration that the connection is active.

+ + +

Example

+
{
+    "type": "start",
+    "autoack": false,
+    "namespace": "ns1",
+    "name": "app1_subscription",
+    "ephemeral": false,
+    "filter": {
+        "message": {},
+        "transaction": {},
+        "blockchainevent": {}
+    },
+    "options": {}
+}
+
+

Field Descriptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
typeWSActionBase.typeFFEnum:
"start"
"ack"
"protocol_error"
"event_batch"
autoackWSStart.autoackbool
namespaceWSStart.namespacestring
nameWSStart.namestring
ephemeralWSStart.ephemeralbool
filterWSStart.filterSubscriptionFilter
optionsWSStart.optionsSubscriptionOptions
+

SubscriptionFilter

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
eventsRegular expression to apply to the event type, to subscribe to a subset of event typesstring
messageFilters specific to message events. If an event is not a message event, these filters are ignoredMessageFilter
transactionFilters specific to events with a transaction. If an event is not associated with a transaction, this filter is ignoredTransactionFilter
blockchaineventFilters specific to blockchain events. If an event is not a blockchain event, these filters are ignoredBlockchainEventFilter
topicRegular 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 topicstring
topicsDeprecated: Please use 'topic' insteadstring
tagDeprecated: Please use 'message.tag' insteadstring
groupDeprecated: Please use 'message.group' insteadstring
authorDeprecated: Please use 'message.author' insteadstring
+

MessageFilter

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
tagRegular expression to apply to the message 'header.tag' fieldstring
groupRegular expression to apply to the message 'header.group' fieldstring
authorRegular expression to apply to the message 'header.author' fieldstring
+

TransactionFilter

+ + + + + + + + + + + + + + + +
Field NameDescriptionType
typeRegular expression to apply to the transaction 'type' fieldstring
+

BlockchainEventFilter

+ + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
nameRegular expression to apply to the blockchain event 'name' field, which is the name of the event in the underlying blockchain smart contractstring
listenerRegular 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 subscriptionsstring
+

SubscriptionOptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
firstEventWhether 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'SubOptsFirstEvent
readAheadThe 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 restartsuint16
withDataWhether 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.bool
batchEvents 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.bool
batchTimeoutWhen batching is enabled, the optional timeout to send events even when the batch hasn't filled.string
fastackWebhooks only: When true the event will be acknowledged before the webhook is invoked, allowing parallel invocationsbool
urlWebhooks only: HTTP url to invoke. Can be relative if a base URL is set in the webhook plugin configstring
methodWebhooks only: HTTP method to invoke. Default=POSTstring
jsonWebhooks only: Whether to assume the response body is JSON, regardless of the returned Content-Typebool
replyWebhooks only: Whether to automatically send a reply event, using the body returned by the webhookbool
replytagWebhooks only: The tag to set on the reply messagestring
replytxWebhooks only: The transaction type to set on the reply messagestring
headersWebhooks only: Static headers to set on the webhook request``
queryWebhooks only: Static query params to set on the webhook request``
tlsConfigNameThe name of an existing TLS configuration associated to the namespace to usestring
inputWebhooks only: A set of options to extract data from the first JSON input data in the incoming message. Only applies if withData=trueWebhookInputOptions
retryWebhooks only: a set of options for retrying the webhook callWebhookRetryOptions
httpOptionsWebhooks only: a set of options for HTTPWebhookHTTPOptions
+

WebhookInputOptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
queryA top-level property of the first data input, to use for query parametersstring
headersA top-level property of the first data input, to use for headersstring
bodyA top-level property of the first data input, to use for the request body. Default is the whole first bodystring
pathA top-level property of the first data input, to use for a path to append with escaping to the webhook pathstring
replytxA top-level property of the first data input, to use to dynamically set whether to pin the response (so the requester can choose)string
+

WebhookRetryOptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
enabledEnables retry on HTTP calls, defaults to falsebool
countNumber of times to retry the webhook call in case of failureint
initialDelayInitial delay between retries when we retry the webhook callstring
maxDelayMax delay between retries when we retry the webhookcallstring
+

WebhookHTTPOptions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field NameDescriptionType
proxyURLHTTP proxy URL to use for outbound requests to the webhookstring
tlsHandshakeTimeoutThe max duration to hold a TLS handshake alivestring
requestTimeoutThe max duration to hold a TLS handshake alivestring
maxIdleConnsThe max number of idle connections to hold pooledint
idleTimeoutThe max duration to hold a HTTP keepalive connection between callsstring
connectionTimeoutThe maximum amount of time that a connection is allowed to remain with no data transmitted.string
expectContinueTimeoutSee ExpectContinueTimeout in the Go docsstring
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/releasenotes/1.1_migration_guide/index.html b/v1.3.1/releasenotes/1.1_migration_guide/index.html new file mode 100644 index 000000000..c153bb4a1 --- /dev/null +++ b/v1.3.1/releasenotes/1.1_migration_guide/index.html @@ -0,0 +1,3723 @@ + + + + + + + + + + + + + + + + + + + + + + + v1.1.0 Migration Guide - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

v1.1.0 Migration Guide

+

Overview

+

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

+

If seamless data preservation is not required, you can simply create a new network from scratch using FireFly v1.1.0.

+

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.

+

Before Upgrading

+

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.

+

Common Steps

+

Upgrade to latest v1.0.x patch release

+

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.

+

Fix any deprecated config usage

+

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.

+

You can utilize the ffconfig tool to automatically check and fix deprecated config with a command such as:

+
ffconfig migrate -f <input-file> -o <output-file> --to 1.0.4
+
+

This should ensure your config file is acceptable to 1.0.x or 1.1.x.

+

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.

+

Less Common Situations

+

Record all broadcast namespaces in the config file

+
+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). + +
+ +

Identify queries for organization/node identities

+
+Expand for migration details only if your application queries /network/organizations or /network/nodes. + +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. + +
+ +

Identify usage of changed APIs

+
+Expand for migration details on all changes to /namespaces, /status, and /network 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. + +
/network/diddocs/{did}
+/network/nodes
+/network/nodes/{nameOrId}
+/network/nodes/self
+/network/organizations
+/network/organizations/{nameOrId}
+/network/organizations/self
+/status
+/status/batchmanager
+
+ +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. + +
/network/identities - replaced by existing /namespaces/{ns}/identities
+/network/identities/{did} - replaced by new /namespaces/{ns}/identities/{did}
+
+ +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. + +
/status/pins - moved to /namespaces/{ns}/pins (or /pins to query the default namespace)
+/status/websockets - moved to /websockets
+
+ +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. + +
/namespaces - removed all fields except "name", "description", "created"
+/namespaces/{ns} - same as above
+/namespaces/{ns}/status - removed "defaults"
+
+ +
+ +

Adjust or remove usage of admin APIs

+
+Expand for migration details on all changes to /admin and /spi. + +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. + +
+ +

Performing the Upgrade

+

Backup current data

+

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.

+

Upgrade FireFly and all dependencies

+

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.

+

After Upgrading

+

Ensure nodes start without errors

+

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.

+

Re-broadcast organization and node identities

+

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 /network/organizations/self and /network/nodes/self (or, if your application uses a non-default namespace, by invoking the /namespace/{ns}-prefixed versions of these APIs).

+

This will ensure that queries to /network/organizations and /network/nodes 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").

+

Update config file to latest format

+

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.

+

You can utilize the ffconfig tool to automatically check and fix deprecated config with a command such as:

+
ffconfig migrate -f <input-file> -o <output-file>
+
+

Upgrading the Multi-Party Contract

+

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.

+

After upgrading FireFly itself, it is recommended to upgrade your multi-party system to the +latest contract version by following these steps.

+
    +
  1. Compile and deploy an instance of the new FireFly contract (linked above) to your blockchain, using ff deploy or a similar method.
    2. +
  2. Edit the config file on each node in your network, to add the new contract to the multi-party contract list like so:
    3. +
+
namespaces:
+  predefined:
+  - name: default
+    multiparty:
+      enabled: true
+      contract:
+      - location:
+          address: 0x09f107d670b2e69a700a4d9ef1687490ae1568db
+      - location:
+          address: 0x1bee32b37dc48e99c6b6bf037982eb3bee0e816b
+
+

This example assumes 0x09f1... represents the address of the original contract, and 0x1bee... 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).

+
    +
  1. After updating each node's configuration, restart the node and ensure it starts without issues.
    2. +
  2. Have any member of the multi-party network invoke the /namespaces/{ns}/network/action FireFly API with a body of {"type": "terminate"}. This will terminate the old contract and instruct all members to move simultaneously to the newly configured one.
    3. +
  3. Verify success by querying /namespaces/{ns}/status on each node and checking that the active multi-party contract matches the new address.
    4. +
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/releasenotes/1.2_migration_guide/index.html b/v1.3.1/releasenotes/1.2_migration_guide/index.html new file mode 100644 index 000000000..6c745930d --- /dev/null +++ b/v1.3.1/releasenotes/1.2_migration_guide/index.html @@ -0,0 +1,3866 @@ + + + + + + + + + + + + + + + + + + + + + + + v1.2.0 Migration Guide - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

v1.2.0 Migration Guide

+

Overview

+

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.

+

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.

+

Tokens considerations

+

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.

+

Sample token contract deprecations

+

In FireFly v1.2.0 two of the old, lesser used sample token contracts have been deprecated. The ERC20NoData and ERC721NoData contracts have been updated and the previous versions are no longer supported, unless you set the USE_LEGACY_ERC20_SAMPLE=true or USE_LEGACY_ERC721_SAMPLE=true environment variables for your token connector.

+

For more details you can read the description of the pull requests (#104 and #109) where these changes were made.

+

Differences from v1.1.0

+

Optional fields

+

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.

+

Auto incrementing token index

+

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.

+
+

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.

+
+

Data management considerations

+

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.

+

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.

+

Differences from v1.1.0

+

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.

+
+

NOTE: If data has been published to IPFS, it cannot be deleted completely. You can still call the DELETE method on it, and it will be removed from FireFly's database and Data Exchange, but the payload will still persist in IPFS.

+
+

Application considerations

+

Optional tokens fields

+

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.

+

Transaction output details

+

In previous versions of FireFly, transaction output details used to appear under the output 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 fetchStatus=true query parameter when querying for an Operation. Additionally the details have moved from the output field to a new detail 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.

+
+v1.2.0 Operation response body with `fetchStatus=true` + +
+{
+  "id": "2b0ec132-2abd-40f0-aa56-79871a7a23b9",
+  "namespace": "default",
+  "tx": "cb0e6de1-50a9-44f2-a2ff-411f6dcc19c9",
+  "type": "blockchain_invoke",
+  "status": "Succeeded",
+  "plugin": "ethereum",
+  "input": {
+    "idempotencyKey": "5a634941-29cb-4a4b-b5a7-196331723d6d",
+    "input": {
+      "newValue": 42
+    },
+    "interface": "46189886-cae5-42ff-bf09-25d4f58d649e",
+    "key": "0x2ecd8d5d97fb4bb7af0fbc27d7b89fd6f0366350",
+    "location": {
+      "address": "0x9d7ea8561d4b21cba495d1bd29a6d3421c31cf8f"
+    },
+    "method": {
+      "description": "",
+      "id": "d1d2a0cf-19ea-42c3-89b8-cb65850fb9c5",
+      "interface": "46189886-cae5-42ff-bf09-25d4f58d649e",
+      "name": "set",
+      "namespace": "default",
+      "params": [
+        {
+          "name": "newValue",
+          "schema": {
+            "details": {
+              "type": "uint256"
+            },
+            "type": "integer"
+          }
+        }
+      ],
+      "pathname": "set",
+      "returns": []
+    },
+    "methodPath": "set",
+    "options": null,
+    "type": "invoke"
+  },
+  "output": {
+    "Headers": {
+      "requestId": "default:2b0ec132-2abd-40f0-aa56-79871a7a23b9",
+      "type": "TransactionSuccess"
+    },
+    "protocolId": "000000000052/000000",
+    "transactionHash": "0x9adae77a46bf869ee97aab38bb5d789fa2496209500801e87bf9e2cce945dc71"
+  },
+  "created": "2023-01-24T14:08:17.371587084Z",
+  "updated": "2023-01-24T14:08:17.385558417Z",
+  "detail": {
+    "created": "2023-01-24T14:08:17.378147625Z",
+    "firstSubmit": "2023-01-24T14:08:17.381787042Z",
+    "gas": "42264",
+    "gasPrice": 0,
+    "history": [
+      {
+        "count": 1,
+        "info": "Success=true,Receipt=000000000052/000000,Confirmations=0,Hash=0x9adae77a46bf869ee97aab38bb5d789fa2496209500801e87bf9e2cce945dc71",
+        "lastOccurrence": null,
+        "time": "2023-01-24T14:08:17.384371042Z"
+      },
+      {
+        "count": 1,
+        "info": "Submitted=true,Receipt=,Hash=0x9adae77a46bf869ee97aab38bb5d789fa2496209500801e87bf9e2cce945dc71",
+        "lastOccurrence": null,
+        "time": "2023-01-24T14:08:17.381908959Z"
+      }
+    ],
+    "id": "default:2b0ec132-2abd-40f0-aa56-79871a7a23b9",
+    "lastSubmit": "2023-01-24T14:08:17.381787042Z",
+    "nonce": "34",
+    "policyInfo": null,
+    "receipt": {
+      "blockHash": "0x7a2ca7cc57fe1eb4ead3e60d3030b123667d18eb67f4b390fb0f51f970f1fba0",
+      "blockNumber": "52",
+      "extraInfo": {
+        "contractAddress": null,
+        "cumulativeGasUsed": "28176",
+        "from": "0x2ecd8d5d97fb4bb7af0fbc27d7b89fd6f0366350",
+        "gasUsed": "28176",
+        "status": "1",
+        "to": "0x9d7ea8561d4b21cba495d1bd29a6d3421c31cf8f"
+      },
+      "protocolId": "000000000052/000000",
+      "success": true,
+      "transactionIndex": "0"
+    },
+    "sequenceId": "0185e41b-ade2-67e4-c104-5ff553135320",
+    "status": "Succeeded",
+    "transactionData": "0x60fe47b1000000000000000000000000000000000000000000000000000000000000002a",
+    "transactionHash": "0x9adae77a46bf869ee97aab38bb5d789fa2496209500801e87bf9e2cce945dc71",
+    "transactionHeaders": {
+      "from": "0x2ecd8d5d97fb4bb7af0fbc27d7b89fd6f0366350",
+      "to": "0x9d7ea8561d4b21cba495d1bd29a6d3421c31cf8f"
+    },
+    "updated": "2023-01-24T14:08:17.384371042Z"
+  }
+}
+
+
+ +
+v1.1.x Operation response body + +
+{
+  "id": "4a1a19cf-7fd2-43f1-8fae-1e3d5774cf0d",
+  "namespace": "default",
+  "tx": "2978a248-f5df-4c78-bf04-711ab9c79f3d",
+  "type": "blockchain_invoke",
+  "status": "Succeeded",
+  "plugin": "ethereum",
+  "input": {
+    "idempotencyKey": "5dc2ee8a-be5c-4e60-995f-9e21818a441d",
+    "input": {
+      "newValue": 42
+    },
+    "interface": "752af5a3-d383-4952-88a9-b32b837ed1cb",
+    "key": "0xd8a27cb390fd4f446acce01eb282c7808ec52572",
+    "location": {
+      "address": "0x7c0a598252183999754c53d97659af9436293b82"
+    },
+    "method": {
+      "description": "",
+      "id": "1739f25d-ab48-4534-b278-58c4cf151bf9",
+      "interface": "752af5a3-d383-4952-88a9-b32b837ed1cb",
+      "name": "set",
+      "namespace": "default",
+      "params": [
+        {
+          "name": "newValue",
+          "schema": {
+            "details": {
+              "type": "uint256"
+            },
+            "type": "integer"
+          }
+        }
+      ],
+      "pathname": "set",
+      "returns": []
+    },
+    "methodPath": "set",
+    "options": null,
+    "type": "invoke"
+  },
+  "output": {
+    "_id": "default:4a1a19cf-7fd2-43f1-8fae-1e3d5774cf0d",
+    "blockHash": "0x13660667b69f48646025a87db603abdeeaa88036e9a1252b1af4ec1fc3e1d850",
+    "blockNumber": "52",
+    "cumulativeGasUsed": "28176",
+    "from": "0xd8a27cb390fd4f446acce01eb282c7808ec52572",
+    "gasUsed": "28176",
+    "headers": {
+      "id": "8dfaabd1-4493-4a64-52dd-762497022ba2",
+      "requestId": "default:4a1a19cf-7fd2-43f1-8fae-1e3d5774cf0d",
+      "requestOffset": "",
+      "timeElapsed": 0.109499833,
+      "timeReceived": "2023-01-24T17:16:52.372449013Z",
+      "type": "TransactionSuccess"
+    },
+    "nonce": "0",
+    "receivedAt": 1674580612482,
+    "status": "1",
+    "to": "0x7c0a598252183999754c53d97659af9436293b82",
+    "transactionHash": "0x522e5aac000f5befba61ddfd707aaf5c61314f47e00cd0c5b779f69dd14bd899",
+    "transactionIndex": "0"
+  },
+  "created": "2023-01-24T17:16:52.368498346Z",
+  "updated": "2023-01-24T17:16:52.48408293Z"
+}
+
+
+ +

Local development considerations

+

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.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/releasenotes/1.3_migration_guide/index.html b/v1.3.1/releasenotes/1.3_migration_guide/index.html new file mode 100644 index 000000000..fc4b95e5e --- /dev/null +++ b/v1.3.1/releasenotes/1.3_migration_guide/index.html @@ -0,0 +1,3836 @@ + + + + + + + + + + + + + + + + + + + + + v1.3.0 Migration Guide - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

v1.3.0 Migration Guide

+ +

Overview

+

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.

+

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.

+

Docker image file permission considerations

+

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.

+
+

⚠️ 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.

+
+

The new default user is 1001. 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:

+
    +
  • firefly-evmconnect
    • +
  • persistence.leveldb.path directory set in the config file
    • +
  • firefly-ethconnect
    • +
  • rest.rest-gateway.openapi.storagePath directory in the config file
    • +
  • rest.rest-gateway.openapi.eventsDB directory in the config file
    • +
  • firefly-fabconnect
    • +
  • receipts.leveldb.path directory in the config file
    • +
  • events.leveldb.path directory in the config file
    • +
  • firefly-dataexchange-https
    • +
  • Data directory set by the DATA_DIRECTORY environment variable (default /data)
    • +
+

API definition/publication considerations

+

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.

+

These following described changes impact contract interfaces, contract APIs, and token pools.

+

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.

+

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

+

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 DELETE APIs to remove the resource.

+

In FireFly v1.2.0 to create one of the affected resources and publish it to other parties, a POST 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.

+

Contract interfaces

+

Previously, to create a contract interface a POST call would be made to /contracts/interfaces and the interface would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the publish=true query parameter, or a subsequent API call can be made on an unpublished interface on POST /contracts/interfaces/{name}/{version}/publish specifying the name and version of the interface.

+

For an exact view of the changes to contract interfaces, see PR #1279.

+

Contract APIs

+

Previously, to create a contract API a POST call would be made to /apis and the API would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the publish=true query parameter, or a subsequent API call can be made on an unpublished API on /apis/{apiName}/publish specifying the name of the API.

+

For an exact view of the changes to contract APIs, see PR #1322.

+

Token pools

+

Previously, to create a token pool a POST call would be made to /tokens/pools and the token pool would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the publish=true query parameter, or a subsequent API call can be made on an unpublished token pool on /tokens/pools/{nameOrId}/publish specifying the name or ID of the token pool.

+

For an exact view of the changes to token pools, see PR #1261.

+

Event stream considerations

+

Single event stream per namespace

+

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.

+

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.

+

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 <plugin_topic_name>/<namespace_name>. For example, an event stream for the default namespace with a plugin topic of 0 would now be: 0/default.

+

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.

+

For an exact view of the changes, see PR #1388.

+

Configuration considerations

+

Deprecated configuration

+

In FireFly v1.3.0 deprecated configuration options for the blockchain, database, dataexchange, sharedstorage and tokens plugins have been removed, and can no longer be provided.

+

For an exact view of the changes, see PR #1289.

+

Token pool considerations

+

Activity indicator changes

+

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.

+

Previously, token pools had a state field with an enumerated value which was either pending, or confirmed, this has been replaced with an active boolean field, where true indicates the token pool has been committed onto chain, and false indicated the transaction has not yet been confirmed.

+

For an exact view of the changes, see PR #1305.

+

FabConnect event considerations

+

FabConnect Protocol ID format changes

+

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.

+

For an exact view of the changes, see PR #1345.

+

Local development considerations

+

Go version upgrade

+

FireFly v1.3.0 now uses Go 1.21 across all modules.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/releasenotes/index.html b/v1.3.1/releasenotes/index.html new file mode 100644 index 000000000..5c80d49d2 --- /dev/null +++ b/v1.3.1/releasenotes/index.html @@ -0,0 +1,3633 @@ + + + + + + + + + + + + + + + + + + + + + + + Release Notes - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Full release notes

+

v1.3.1 - Aug 5, 2024

+

What's New:

+
    +
  • Enable contract listeners with multiple filters + See Contract Listeners for details
    • +
  • New multiparty status API at /status/multiparty
    • +
+

v1.3.0 - April 25, 2024

+

Migration guide

+

What's New:

+
    +
  • Enhancements to FireFly Messaging capabilities, allowing off-chain data to be linked to on-chain transactions from custom smart contracts
    • +
  • Sample contract implementation for custom pin contracts
    • +
  • Contract interfaces, contract APIs, and token pools can now be separately defined and published
    • +
  • Support for batching events when delivering over websockets
    • +
  • Lots of bug fixes and miscellaneous enhancements
    • +
+

v1.2.0 - February 6, 2023

+

Migration guide

+

What's New:

+
    +
  • Enhanced support for token contracts generated by the OpenZeppelin Wizard
    • +
  • Custom smart contract error types are now returned on the API
    • +
  • Data objects and associated blobs can now be deleted
    • +
  • Optional dynamic reload of core configuration file
    • +
  • The X-FireFly-Request-ID HTTP header is now passed through to FireFly dependency microservices
    • +
  • Custom HTTP headers can be passed through to FireFly dependency microservices
    • +
  • Evmconnect is now the default blockchain connector for Ethereum based FireFly stacks
    • +
+

Release Notes

+

Full release notes

+

v1.1.0 - September 12, 2022

+

Migration guide

+

What's New:

+
    +
  • Gateway Mode: Connect to many chains with auto-indexing of activities
    • +
  • Public EVM Chain Support: Manage public chain connections including Ethereum, Polygon, Arbitrum, Binance Smart Chain, Moonbeam, and more.
    • +
  • Namespaces: Isolated environments within a FireFly runtime allowing independent configuration of plugin and infrastructure components and more
    • +
  • Connector Toolkit: Quickly build custom connectors
    • +
  • Pluggable API Security: Plug in your own API security
    • +
  • Mass Scale Tokens: Support many parallel copies of token plugins for mass scale
    • +
+

v1.0.3 - July 07, 2022

+

What's New:

+
    +
  • Adds support for custom URIs for non-fungible tokens and documentation updates
    • +
  • Deprecate default value for "ffdx"
    • +
  • Back port of custom URI support for non-fungible tokens
    • +
  • Update token connector versions
    • +
  • Back port of "FAQ and FireFly Tutorial updates"
    • +
+

v1.0.2 - May 12, 2022

+

What's New:

+
    +
  • Fix invocations on custom Fabric chaincode, which were not properly reporting success/failure status back to FireFly (along with other minor bugfixes).
    • +
  • De-duplicate existing token approvals in database migration
    • +
  • Backport docs generation and versioning code for 1.0 stream
    • +
  • Default fabconnect calls to async
    • +
  • Set message header type of broadcast/private
    • +
+

v1.0.1 - May 09, 2022

+

What's New:

+
    +
  • Fixes for token approvals - previously approvals would intermittently be missed by FireFly or recorded with incorrect details.
    • +
  • 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.
    • +
+

v1.0.0 - April 28, 2022

+

This release includes lots of major hardening, performance improvements, and bug fixes, as well as more complete documentation and OpenAPI specifications.

+

What's New:

+
    +
  • Massive performance improvements across the board
    • +
  • Up-to-date documentation and fully annotated OpenAPI specification
    • +
  • Overhaul of UI
    • +
  • Cleaner logs and error messages
    • +
  • Lots of bug fixes and miscellaneous enhancements
    • +
+

v0.14.0 - March 22, 2022

+

What's New:

+
    +
  • Major UI updates including Activity, Blockchain, Off-Chain, Tokens, Network Map, and My Node sections
    • +
  • Custom contract APIs
    • +
  • Enhanced subscription filters
    • +
  • Event API enrichment
    • +
  • Performance updates
    • +
  • Bug fixes
    • +
+

v0.13.0 - February 14, 2022

+

What's New:

+
    +
  • Hardening release with significant rework to core of FireFly, mostly to fix issues exposed by the performance testing.
    • +
  • Support for running on ARM-based M1 processors
    • +
  • Rewrite of the message batching and event aggregation logic inside FireFly, to fix numerous edge cases with lost or hung messages
    • +
  • Hardening of operations and transactions to behave more consistently across all types
    • +
  • Metrics reporting to Prometheus
    • +
  • Continued development to support custom on-chain logic (still in preview)
    • +
+

v0.12.0 - February 02, 2022

+

What's New:

+
    +
  • All APIs deprecated in v0.11.0 or earlier are removed
    • +
  • Preview of custom on-chain logic
    • +
  • Support for new ERC20 / ERC721 connector
    • +
  • Overhaul of Transaction type and new BlockchainEvent type
    • +
  • Support for delivery confirmations via DX plugin
    • +
+

v0.11.0 - November 22, 2021

+

What's New:

+
    +
  • Significant hardening and enhanced token functionality
    • +
  • Major web UI overhaul
    • +
  • Optimized database operations for increased transactional throughput
    • +
  • Fixed PostgreSQL database migrations
    • +
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/search/search_index.json b/v1.3.1/search/search_index.json new file mode 100644 index 000000000..7e414c9c3 --- /dev/null +++ b/v1.3.1/search/search_index.json @@ -0,0 +1 @@ +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Hyperledger FireFly","text":"

Hyperledger FireFly is an open source Supernode, a complete stack for enterprises to build and scale secure Web3 applications.

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.

Head to the Understanding FireFly section for more details.

"},{"location":"SUMMARY/","title":"SUMMARY","text":"
  • Home
  • Understanding FireFly
    • Introduction
    • Usage Patterns
    • Key Features
      • overview/key_components/*
    • Web3 Gateway Features
    • Multiparty Features
      • overview/multiparty/*
    • Public and Permissioned
  • Getting Started
    • \u2460 Install the FireFly CLI
    • \u2461 Start your environment
    • \u2462 Use the Sandbox
  • Tutorials
    • tutorials/*
  • Reference
    • reference/*.md
    • Microservices
      • reference/microservices/*.md
    • Types
      • reference/types/*.md
  • Architecture
    • architecture/*
  • Contributors
    • contributors/*
  • API Spec
  • FAQs
  • Release Notes
    • releasenotes/*
"},{"location":"architecture/blockchain_connector_framework/","title":"Blockchain Connector Toolkit","text":""},{"location":"architecture/blockchain_connector_framework/#blockchain-connector-framework","title":"Blockchain Connector Framework","text":"

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.

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.

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.

"},{"location":"architecture/blockchain_connector_framework/#connector-toolkit-architecture","title":"Connector Toolkit Architecture","text":"

The core component of the FireFly Connector Framework for Blockchains is a Go module called FireFly Transaction Manager (FFTM).

FFTM is responsible for:

  • Submission of transactions to blockchains of all types

  • Protocol connectivity decoupled with additional lightweight API connector

  • Easy to add additional protocols that conform to normal patterns of TX submission / events

  • Monitoring and updating blockchain operations

  • Receipts

  • Confirmations

  • Extensible transaction handler with capabilities such as:

  • Nonce management: idempotent submission of transactions, and assignment of nonces

  • Transaction management: pre-signing transactions, resubmission, customizable policy engine
  • Gas management: Gas Gas station API integration

  • Transaction process history

  • Event streaming

  • Protocol agnostic event polling/streaming support
  • Reliable checkpoint restart
  • At least once delivery API
"},{"location":"architecture/blockchain_connector_framework/#assumptions-requirements","title":"Assumptions / Requirements","text":"

The framework is currently constrained to blockchains that adhere to certain basic principals:

  1. Has transactions

  2. That are signed

  3. That can optionally have gas semantics (limits and prices, expressed in a blockchain specific way)

  4. Has events (or \"logs\")

  5. That are emitted as a deterministic outcome of transactions

  6. Has blocks

  7. Containing zero or more transactions, with their associated events

  8. With a sequential numeric order
  9. With a hash

  10. With a parent hash

  11. Has finality for transactions & events that can be expressed as a level of confidence over time

  12. Confirmations: A number of sequential blocks in the canonical chain that contain the transaction

"},{"location":"architecture/blockchain_connector_framework/#nonce-management-in-the-simple-transaction-handler","title":"Nonce management in the simple transaction handler","text":"

The nonces for transactions is assigned as early as possible in the flow:

  • Before the REST API for submission of the transaction occurs
  • After the FFCAPI blockchain connector verifies the transaction can be encoded successfully to the chain
  • With protection against multiple parallel API requests for the same signing address
  • With stateful persistence meaning the connector knows about all nonces it previously allocated, to avoids duplicates

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.

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.

"},{"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":"

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.

Be careful that the signing keys for transactions you stream through the Nonce Management of the FireFly blockchain connector are not used elsewhere.

If you must have multiple systems performing nonce management against the same keys you use with FireFly nonce management, you can set the transactions.nonceStateTimeout to 0 (or a low threshold like 100ms) to cause the nonce management to query the pending transaction pool of the node every time a nonce is allocated.

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.

"},{"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":"

The \"at source\" approach to ordering used in FFTM could be compared with the \"at target\" allocation of nonces used in EthConnect).

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.

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.

However, \"at target\" comes with two compromises that mean FFTM chose the \"at source\" approach was chosen for FFTM:

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

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

"},{"location":"architecture/blockchain_connector_framework/#transaction-handler","title":"Transaction Handler","text":"

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.

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.

A reference implementation is provided that:

  • Submits transactions via the underlying FFCAPI
  • Estimates gas price in one of three modes:
  • Fixed: It is specified via configuration
  • Connector: The FFCAPI is used to estimate the gas price (e.g. eth_gasPrice for EVM JSON/RPC)
  • Gas Oracle: A REST API is called the the result mapped via a Go template
  • Re-submits transactions after a configurable stale time
  • Record detailed information about transaction sub-status and actions
  • Emit customized metrics for transaction processing

The reference implementation is available here

"},{"location":"architecture/blockchain_connector_framework/#event-streams","title":"Event Streams","text":"

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.

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.

Some high architectural principals that informed the code:

  • Event Stream
  • A delivery stream of events that have been confirmed
  • Only events that have reached finality are delivered to an event stream
  • FireFly creates a single event stream per namespace from core
  • Each token connector creates a single event stream
  • If one event stream is blocked, it must not block other streams in the FFTM based runtime
  • Listener (/Subscription)
  • A blockchain specific specification for a set of events to listen to
  • Specifies an initial block to listen from, and will replay all events from that block
  • Can have multiple blockchain specific filters, to match multiple events
  • The order of delivery within a listener matches the blockchain across all filters > - Note that the EVMConnect implementation of FFCAPI attempts to make this true across all listeners > on an event stream. However, this is impossible when a new listener has been added, > and that listener is catching up from an old block.
  • Compatibility
  • Has breaking changes from the API of EthConnect
  • A component that has been upgraded to support EVMConnect, can maintain backwards compatibility with EthConnect
  • Batching & Checkpoints
  • Delivery on event streams is via batches, with a single confirmation for each batch
  • At-least-once delivery of batches
  • Checkpoints are written after each batch
  • Chain head stability
  • A configurable section of the head of the chain is considered unstable
  • If no events have been delivered for a listener, checkpoints are still moved forwards
  • These empty checkpoints will never be written in the unstable head of the chain
  • Confirmation manager
  • Plugged in between detection of the events, and assembling into batches
  • Determines the final order based on order of confirmation on the blockchain

"},{"location":"architecture/internal_event_sequencing/","title":"Internal Event Sequencing","text":""},{"location":"architecture/internal_event_sequencing/#overview","title":"Overview","text":"

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.

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

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:

  • Private messaging in the Data Exchange
  • The blockchain ledger(s) themselves, which are a stream of sequenced events
  • The event dispatcher delivering messages to applications that have been sequenced by FireFly

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.

The sequence is made deterministic:

  • Globally to all apps within the scope of the ledger, when a Blockchain ledger is used to pin events (see #10)
  • Locally for messages delivered through a single FireFly node into the network
  • Locally for all messages delivered to applications connected to a FireFly node, across blockchain
"},{"location":"architecture/internal_event_sequencing/#app-instances","title":"App Instances","text":"
  • Broadcast messages to the network
  • Ingest ack when message persisted in local messages table
  • Consume events via Websocket connection into FireFly
"},{"location":"architecture/internal_event_sequencing/#outbound-sequencers","title":"Outbound Sequencers","text":"
  • Broadcast or Private through IPFS or Private Data Storage
  • Long-running leader-elected jobs listening to the database (via event tables in SQL, etc.)
"},{"location":"architecture/internal_event_sequencing/#inbound-aggregator","title":"Inbound Aggregator","text":"
  • Triggered each time an event is detected by the associated plugin.
  • It is the responsibility of the plugin to fire events sequentially. Can be workload managed but must be sequential.
"},{"location":"architecture/internal_event_sequencing/#events-table","title":"Events Table","text":"
  • Deliberately lightweight persisted object, that is generated as a byproduct of other persistent actions.
  • Records the local sequence of a specific event within the local node.
  • The highest level event type is the confirmation of a message, however the table can be extended for more granularity on event types.
"},{"location":"architecture/internal_event_sequencing/#subscription-manager","title":"Subscription Manager","text":"
  • Responsible for filtering and delivering batches of events to the active event dispatchers.
  • Records the latest offset confirmed by each dispatcher.
"},{"location":"architecture/internal_event_sequencing/#event-dispatcher","title":"Event Dispatcher","text":"
  • Created with leadership election when WebSocket connection is made from an app into FireFly.
  • Extensible to other dispatchers (AMQP, etc.).
"},{"location":"architecture/multiparty_event_sequencing/","title":"Multiparty Event Sequencing","text":""},{"location":"architecture/multiparty_event_sequencing/#transaction-submission","title":"Transaction Submission","text":"
  • An individual FireFly instance preserves the order that it received messages from application instances.
  • Where possible, batching is used to roll-up hundreds of transactions into a single blockchain transaction.
  • Blockchain allows these messages to be globally sequenced with messages submitted by other members of the network.
"},{"location":"architecture/multiparty_event_sequencing/#blockchain-ordering","title":"Blockchain Ordering","text":"
  • All member FireFly runtimes see every transaction in the same sequence.
  • This includes when transactions are being submitted by both sides concurrently.
"},{"location":"architecture/multiparty_event_sequencing/#message-assembly","title":"Message Assembly","text":"
  • A queue of events is maintained for each matching app subscription.
  • The public/private payloads travel separately to the blockchain, and arrive at different times. FireFly assembles these together prior to delivery.
  • If data associated with a blockchain transaction is late, or does not arrive, all messages on the same \"context\" will be blocked.
  • 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.
"},{"location":"architecture/multiparty_event_sequencing/#event-processing","title":"Event Processing","text":"
  • Events are processed consistently by all parties.
  • All FireFly runtimes see every event that they are subscribed to, in the same sequence.
  • 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.
"},{"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":"

The core architecture of a FireFly node can be broken down into the following three areas:

  • The various runtimes encapsulating the node.
  • The core runtime responsibilities and pluggable elements.
  • The actual code running inside the node.

"},{"location":"architecture/node_component_architecture/#runtimes","title":"Runtimes","text":"

What fundamentally is a node - left side of the above diagram.

  • It is a collection of multiple runtimes with a single unified HTTPS/Websocket API (exposed by the Core).
  • It has a private database, containing your private data, and data received from others in the network.
  • It has connectivity out to other parties in the network, through runtimes (Blockchain, Shared Filesystems, Messaging etc.).
"},{"location":"architecture/node_component_architecture/#responsibilities-pluggable-elements","title":"Responsibilities & Pluggable Elements","text":"

What are the core runtime responsibilities, and pluggable elements - right side of the above diagram.

  • The core elements of function that FireFly performs, and which runtime is responsible.
  • This means some insight into core itself, and the jobs it performs, but not full code structure.
  • More importantly, what the split of responsibilities is between Connectors and Infrastructure Runtimes.
    • Connectors are the bridging runtimes, that know how to talk to a particular runtime.
    • They run separately to the core (like a microservice architecture of an app).
    • They can be written in any language (not just Go) - Java, TypeScript, Rust, Python, .NET etc.
    • They can use any network transport (not just HTTPS/Websockets) - GRPC, AMQP, UDP etc.
    • They connect to the core with a Golang shim - see separate Plugin Architecture discussion. > - In some special cases (like the Database) the Golang shim does not need a connector runtime.
    • Infrastructure Runtimes are the core runtimes for multi-party system activities.
    • Blockchain nodes - Ethereum (Hyperledger Besu, Quorum, Geth), Hyperledger Fabric, Corda etc.
    • Shared strorage - IPFS etc.
    • Database - PostreSQL, CouchDB etc.
"},{"location":"architecture/node_component_architecture/#code-structure","title":"Code Structure","text":"

What is the code structure inside the core.

  • The README.md is the reference for this.
  • Developers contributing to FireFly, on the core, or building new plugins, need this level of detail.
    • A reconciliation is underway to ensure the medium-level view correlates well with this code structure.
"},{"location":"architecture/ping_pong_txflow/","title":"Example Transaction Flow (Ping Pong)","text":""},{"location":"architecture/ping_pong_txflow/#overview","title":"Overview","text":"

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.

  • Party A: Establish existence of a digital asset.
  • Nothing more than some binary data (an image, a document, a specification etc.).
  • Party A: Broadcast some information about that asset to everyone, using blockchain to record, sequence and propagate.
  • So people can find it, or part of a more sophisticated workflow.
  • Party B: Request the actual data - with evidence of that request tied to the blockchain.
  • Including some private data that's sent to the Party A, reliably off-chain.
  • Party A: Authorize the request, and send the data privately to Party B.
  • In this example there's no blockchain involved in this step.

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.

The \"tramlines\" view shows how FireFly's pluggable model makes the job of the developer really simple:

  • A few simple API calls from a modern web app.
  • Event triggered execution of application logic.

This is deliberately a simple flow, and all kinds of additional layers might well layer on (and fit within the FireFly model):

  • NFTs to track ownership etc. related to the digital asset.
  • Tokenized rewards/payments integrated with the authorization of the transfer of data.
  • Proof of deterministic execution of the logic to perform the authorization (on-chain, TEEs, ZKPs).
  • Human workflow, that is of course completely non-deterministic.
  • Multiple additional process steps, deterministic or not.
  • Inclusion of multiple additional parties (maybe it's a request-for-tender, submit-tender flow for example).
  • etc.
"},{"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":"
  • Upload Blob of the actual data
  • Returns a hash of the payload
  • Upload JSON containing the public index data
  • Includes the hash of the full payload
  • Send a broadcast message with the public index data
  • Agree upon a primary key of the data as the \"context\"
"},{"location":"architecture/ping_pong_txflow/#receive-public-description-request-asset-data-member-2","title":"Receive Public Description & Request Asset Data (Member 2)","text":"
  • Store data in your own off-chain database for rich, efficient query
  • Run automated logic to decide if you want to request the full data
  • Upload JSON for data request
  • Send a private message
  • Backed by blockchain in this flow
"},{"location":"architecture/ping_pong_txflow/#authorize-transfer-data-member-1","title":"Authorize & Transfer Data (Member 1)","text":"
  • Inspect the request data
  • Retrieve data asset by hash
  • Send the private data in a private message
  • No blockchain in this flow
"},{"location":"architecture/ping_pong_txflow/#receive-data-asset-member-2","title":"Receive Data Asset (Member 2)","text":"
  • Receive a link to your local copy of the asset data
"},{"location":"architecture/plugin_architecture/","title":"Plugin Architecture","text":"

This diagram shows the various plugins that are currently in the codebase and the layers in each plugin

This diagram shows the details of what goes into each layer of a FireFly plugin

"},{"location":"architecture/plugin_architecture/#overview","title":"Overview","text":"

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:

This architecture is designed to provide separations of concerns to account for:

  • Differences in code language for the low-level connection to a backend (Java for Corda for example)
  • Differences in transports, particularly for delivery of events:
  • Between FireFly Core and the Connector
    • Different transports other than HTTPS/WebSockets (GRPC etc.), and different wire protocols (socket.io, etc.)
  • Between the Connector and the underlying Infrastructure Runtime
    • Often this is heavy lifting engineering within the connector
  • Differences in High Availability (HA) / Scale architectures
  • Between FireFly Core, and the Connector
    • Often for event management, and active/passive connector runtime is sufficient
  • Between the Connector and the Infrastructure Runtime
    • 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
"},{"location":"architecture/plugin_architecture/#firefly-core","title":"FireFly Core","text":"
  • Golang
  • N-way scalable cluster
  • Database is also pluggable via this architecture
  • No long lived in-memory processing
  • All micro-batching must be recoverable
  • Driven by single configuration set
  • Viper semantics - file, env var, cmdline flags
"},{"location":"architecture/plugin_architecture/#plugin-for-connector","title":"Plugin for Connector","text":"
  • Golang
  • Statically compiled in support at runtime
  • Go dynamic plugin support too immature
  • Must be 100% FLOSS code (no GPL/LGPL etc.)
  • Contributed via PR to FF Core
  • Intended to be lightweight binding/mapping
  • Must adhere to FF Core Coding Standards
  • Scrutiny on addition of new frameworks/transports
"},{"location":"architecture/plugin_architecture/#connector","title":"Connector","text":"
  • Node.js / Java / Golang, etc.
  • Runs/scales independently from FF core
  • Coded in any language, OSS or proprietary
  • One runtime or multiple
  • HA model can be active/passive or active/active
  • Expectation is all plugins need a connector
  • Some exceptions exist (e.g. database plugin)
"},{"location":"architecture/plugin_architecture/#infrastructure-runtime","title":"Infrastructure Runtime","text":"
  • Besu, Quorum, Corda, Fabric, IPFS, Kafka, etc.
  • Runs/scales independently from FF Core
  • Coded in any language, OSS or proprietary
  • Not specific to FireFly
  • HA model can be active/passive or active/active
"},{"location":"contributors/","title":"Contributors' Guide","text":"

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.

\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

"},{"location":"contributors/#connect-with-us-on-discord","title":"\ud83d\ude80 Connect with us on Discord","text":"

You can chat with maintainers and other contributors on Discord in the firefly channel: https://discord.gg/hyperledger

Join Discord Server

"},{"location":"contributors/#join-our-community-calls","title":"\ud83d\udcc5 Join our Community Calls","text":"

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.

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.

"},{"location":"contributors/#find-your-first-issue","title":"\ud83d\udd0d Find your first issue","text":"

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.

See \"Good First Issues\"

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.

Here are some other suggestions of places to get started, based on experience you may already have:

"},{"location":"contributors/#any-level-of-experience","title":"Any level of experience","text":"

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.

Here are some detailed instructions on Contributing to Documentation

"},{"location":"contributors/#go-experience","title":"Go experience","text":"

If you have some experience in Go and really want to jump into FireFly, the FireFly Core is the heart of the project.

Here are some detailed instructions on Setting up a FireFly Core Development Environment.

"},{"location":"contributors/#little-or-no-go-experience-but-want-to-learn","title":"Little or no Go experience, but want to learn","text":"

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.

"},{"location":"contributors/#typescript-experience","title":"TypeScript experience","text":"

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.

"},{"location":"contributors/#reacttypescript-experience","title":"React/TypeScript experience","text":"

If you want to do some frontend development, the FireFly UI is written in TypeScript and React.

"},{"location":"contributors/#go-and-blockchain-experience","title":"Go and blockchain experience","text":"

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.

"},{"location":"contributors/#make-changes","title":"\ud83d\udcdd Make changes","text":"

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.

"},{"location":"contributors/#commit-with-developer-certificate-of-origin","title":"\ud83d\udcd1 Commit with Developer Certificate of Origin","text":"

As with all Hyperledger repositories, FireFly requires proper sign-off on every commit that is merged into the main 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 -s flag when you commit changes.

git commit -s -m \"Your commit message\"\n

This will add a string like this to the end of your commit message:

\"Signed-off-by: Your Name <your-email@address>\"\n

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 -s \ud83d\ude42

"},{"location":"contributors/#open-a-pull-request","title":"\ud83d\udce5 Open a Pull Request","text":"

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.

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.

Thanks for your interest in collaborating on this project!

"},{"location":"contributors/#inclusivity","title":"Inclusivity","text":"

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:

  • Consider that users who will read the docs are from different background and cultures and that they have different preferences.
  • Avoid potential offensive terms and, for instance, prefer \"allow list and deny list\" to \"white list and black list\".
  • 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.
  • We suggest to refer to Microsoft bias free writing guidelines and Google inclusive doc writing guide as starting points.
"},{"location":"contributors/advanced_cli_usage/","title":"Advanced CLI Usage","text":"

This page details some of the more advanced options of the FireFly CLI

"},{"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 manifest.json file","text":"

FireFly has a manifest.json 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.

Here is an example of what the manifest.json looks like:

{\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
"},{"location":"contributors/advanced_cli_usage/#default-cli-behavior-for-releases","title":"Default CLI behavior for releases","text":"

When creating a new stack, the CLI will by default, check the latest non-pre-release version of FireFly and look at its manifest.json 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 docker-compose.yml file for that stack, so restarting or resetting a stack will never pull a newer image.

"},{"location":"contributors/advanced_cli_usage/#running-a-specific-release-of-firefly","title":"Running a specific release of FireFly","text":"

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 --release or -r flag. For example, to explicitly use v0.9.0 run this command to initialize the stack:

ff init -r v0.9.0\n
"},{"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":"

If you need to run an unreleased version of FireFly or one of its microservices, you can point the CLI to a specific manifest.json on your local disk. To do this, use the --manifest or -m flag. For example, if you have a file at ~/firefly/manifest.json:

ff init -m ~/firefly/manifest.json\n

If you need to test a locally built docker image of a specific service, you'll want to edit the manifest.json before running ff init. 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.

"},{"location":"contributors/advanced_cli_usage/#build-a-new-image-of-fabconnect-locally","title":"Build a new image of fabconnect locally","text":"

From the fabconnect project directory, build and tag a new Docker image:

docker build -t ghcr.io/hyperledger/firefly-fabconnect .\n
"},{"location":"contributors/advanced_cli_usage/#edit-your-manifestjson-file","title":"Edit your manifest.json file","text":"

Next, edit the fabconnect section of the manifest.json file. You'll want to remove the tag and sha and a \"local\": true field, so it looks like this:

...\n  \"fabconnect\": {\n    \"image\": \"ghcr.io/hyperledger/firefly-fabconnect\",\n    \"local\": true\n  },\n...\n
"},{"location":"contributors/advanced_cli_usage/#initialize-the-stack-with-the-custom-manifestjson-file","title":"Initialize the stack with the custom manifest.json file","text":"
 ff init local-test -b fabric -m ~/Code/hyperledger/firefly/manifest.json\n ff start local-test\n

If you are iterating on changes locally, you can get the CLI to use an updated image by doing the following:

  • Whenever the CLI does its first time setup, it will use your newly built local docker image
  • If you've already run the stack, you can run ff reset <stack_name> and ff start <stack_name> to reset the data, and use the newer image
"},{"location":"contributors/advanced_cli_usage/#running-a-locally-built-firefly-core-image","title":"Running a locally built FireFly Core image","text":"

You may have noticed that FireFly core is actually not listed in the manifest.json file. 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.

"},{"location":"contributors/advanced_cli_usage/#build-a-new-image-of-firefly-locally","title":"Build a new image of FireFly locally","text":"

From the firefly project directory, build and tag a new Docker image:

make docker\n
"},{"location":"contributors/advanced_cli_usage/#initialize-the-stack-with-the-custom-manifestjson-file_1","title":"Initialize the stack with the custom manifest.json file","text":"
 ff init local-test -m ~/Code/hyperledger/firefly/manifest.json\n ff start local-test\n
"},{"location":"contributors/code_hierarchy/","title":"FireFly Code Hierarchy","text":"

Use the following diagram to better understand the hierarchy amongst the core FireFly components, plugins and utility frameworks:

\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
"},{"location":"contributors/code_overview/","title":"FireFly Code Overview","text":""},{"location":"contributors/code_overview/#developer-intro","title":"Developer Intro","text":"

FireFly is a second generation implementation re-engineered from the ground up to improve developer experience, runtime performance, and extensibility.

This means a simplified REST/WebSocket programming model for app development, and a wider range of infrastructure options for deployment.

It also means a focus on an architecture and code structure for a vibrant open source community.

A few highlights:

  • Golang codebase
  • Strong coding standards, including unit test coverage, translation support, logging and more
  • Fast starting, low memory footprint, multi-threaded runtime
  • OpenAPI 3.0 API specification (Swagger)
  • Generated from the API router code, to avoid divergence with the implementation
  • Active/active HA architecture for the core runtime
  • Deferring to the core database for state high availability
  • Exploiting leader election where required
  • Fully pluggable architecture
  • Everything from Database through to Blockchain, and Compute
  • Golang plugin infrastructure to decouple the core code from the implementation
  • Remote Agent model to decouple code languages, and HA designs
  • Updated API resource model
  • Asset, Data, Message, Event, Topic, Transaction

  • Added flexibility, with simplified the developer experience:

  • Versioning of data definitions

  • Introducing a first class Context construct link related events into a single sequence
  • Allow many pieces of data to be attached to a single message, and be automatically re-assembled on arrival
  • Clearer separation of concerns between the FireFly DB and the Application DB
  • Better search, filter and query support

## Directories

  • internal: The core Golang implementation code
  • pkg: Interfaces intended for external project use
  • cmd: The command line entry point
  • smart_contracts: smart contract code for FireFly's onchain logic
"},{"location":"contributors/code_repositories/","title":"Code Repositories","text":"

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.

But not to worry, one of those repos is a CLI designed to get you running with all the components you need in minutes!

  • CLI / Developer experience
  • FireFly Samples
  • UI Explorer
  • Core
  • HTTP Data Exchange
  • Ethereum (Hyperledger Besu / Quorum) connector
  • Corda connector
  • Hyperledger Fabric connector
  • Token connector reference implementation (ERC1155)

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.

"},{"location":"contributors/dev_environment_setup/","title":"Setting up a FireFly Core Development Environment","text":"

This guide will walk you through setting up your machine for contributing to FireFly, specifically the FireFly core.

"},{"location":"contributors/dev_environment_setup/#dependencies","title":"Dependencies","text":"

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.

  • Go 1.21
  • make
  • GCC
  • openssl
"},{"location":"contributors/dev_environment_setup/#install-the-firefly-cli","title":"Install the FireFly CLI","text":"

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.

"},{"location":"contributors/dev_environment_setup/#installing-go-and-setting-up-your-gopath","title":"Installing Go and setting up your GOPATH","text":"

We recommend following the instructions on golang.org to install Go, rather than installing Go from another package magager such as brew. Although it is possible to install Go any way you'd like, setting up your GOPATH may differ from the following instructions.

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 .bashrc or .zshrc, depending on which shell you're using.

Add the following lines to your .bashrc or .zshrc file:

export GOPATH=$HOME/go\nexport GOROOT=\"/usr/local/go\"\nexport PATH=\"$PATH:${GOPATH}/bin:${GOROOT}/bin\"\n
"},{"location":"contributors/dev_environment_setup/#building-firefly","title":"Building FireFly","text":"

After installing dependencies, building FireFly from source is very easy. Just clone the repo:

git clone git@github.com:hyperledger/firefly.git && cd firefly\n

And run the Makefile to run tests, and compile the app

make\n

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:

go install\n
"},{"location":"contributors/dev_environment_setup/#install-the-cli","title":"Install the CLI","text":"

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

"},{"location":"contributors/dev_environment_setup/#set-up-a-development-stack","title":"Set up a development stack","text":"

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.

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.

We'll call this stack dev. We're also going to add --external 1 to the end of our command to create the new stack:

ff init dev --external 1\n

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.

"},{"location":"contributors/dev_environment_setup/#start-the-stack","title":"Start the stack","text":"

To start your new stack simply run:

ff start dev\n

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.

"},{"location":"contributors/dev_environment_setup/#1-from-another-terminal","title":"1) From another terminal","text":"

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 firefly core project directory. Here is an example of the command that the CLI will tell you to run:

firefly -f ~/.firefly/stacks/dev/runtime/config/firefly_core_0.yml\n

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

"},{"location":"contributors/dev_environment_setup/#2-using-an-ide","title":"2) Using an IDE","text":"

If you named your stack dev there is a launch.json 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\".

Now you should have a full FireFly stack up and running, and be able to debug FireFly using your IDE. Happy hacking!

NOTE: Because firefly-ui 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.`

"},{"location":"contributors/dev_environment_setup/#set-up-dev-environment-for-other-components","title":"Set up dev environment for other components","text":"

Refer to Advanced CLI Usage.

"},{"location":"contributors/docs_setup/","title":"Contributing to Documentation","text":"

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.

This doc site is generated by a set of Markdown files in the main FireFly repository, under the ./doc-site directory. You can browse the source for the current live site in GitHub here: https://github.com/hyperledger/firefly/tree/main/doc-site

"},{"location":"contributors/docs_setup/#process-for-updating-documentation","title":"Process for updating documentation","text":"

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:

  1. Fork https://github.com/hyperledger/firefly
  2. Clone your fork locally to your computer
  3. Follow the steps below to view your local copy of the docs in a browser
  4. Make some improvements to the Markdown files
  5. Verify that your changes look they way you want them to in your browser
  6. Create a new git commit with your changes. Be sure to sign-off on your commit by using git commit -s!
  7. Push your changes
  8. Open a Pull Request to incorporate your changes back into the hyperledger/firefly repo

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.

"},{"location":"contributors/docs_setup/#prerequisites","title":"Prerequisites","text":"

To test the documents and update the published site, the following tools are needed:

  • A Bash shell
  • git
  • Python 3
  • The Material for Mkdocs theme.
  • The Mike MkDocs plugin for publishing versions to gh-pages.
  • Not used locally, but referenced in the mkdocs.yml file and needed for deploying the site to gh-pages.
"},{"location":"contributors/docs_setup/#git","title":"git","text":"

git can be installed locally, as described in the Install Git Guide from GitHub.

"},{"location":"contributors/docs_setup/#python-3","title":"Python 3","text":"

Python 3 can be installed locally, as described in the Python Getting Started guide.

"},{"location":"contributors/docs_setup/#virtual-environment","title":"Virtual environment","text":"

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.

cd doc-site\npython3 -m venv venv\nsource venv/bin/activate\n
"},{"location":"contributors/docs_setup/#mkdocs","title":"Mkdocs","text":"

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:

pip install -r requirements.txt\n
"},{"location":"contributors/docs_setup/#verify-setup","title":"Verify Setup","text":"

To verify your setup, check that you can run mkdocs by running the command mkdocs --help to see the help text.

"},{"location":"contributors/docs_setup/#useful-mkdocs-commands","title":"Useful MkDocs Commands","text":"

The commands you will usually use with mkdocs are:

  • mkdocs serve - Start the live-reloading docs server.
  • mkdocs build - Build the documentation site.
  • mkdocs -h - Print help message and exit.
"},{"location":"contributors/docs_setup/#directory-layout","title":"Directory layout","text":"
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
"},{"location":"contributors/release_guide/","title":"Release Guide","text":"

This guide will walk you through creating a release.

"},{"location":"contributors/release_guide/#versioning-scheme","title":"Versioning scheme","text":"

FireFly follows semantic versioning. For more details on how we determine which version to use please see the Versioning Scheme guide.

"},{"location":"contributors/release_guide/#the-manifestjson-file","title":"The manifest.json file","text":"

FireFly has a manifest.json 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 manifest.json file, commit it, and include it in your PR. This will trigger an end-to-end test run, using the specified versions.

Here is an example of what the manifest.json looks like:

{\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

NOTE: You can run make manifest 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 manifest.json file manually, as this script will not fetch those versions.

"},{"location":"contributors/release_guide/#creating-a-new-release","title":"Creating a new release","text":"

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.

"},{"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 Draft a new release button","text":""},{"location":"contributors/release_guide/#3-fill-out-the-form-for-your-release","title":"3) Fill out the form for your release","text":"

It is recommended to start with the auto-generated release notes. Additional notes can be added as-needed.

"},{"location":"contributors/release_guide/#automatic-docker-builds","title":"Automatic Docker builds","text":"

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.

"},{"location":"contributors/version_scheme/","title":"Versioning Scheme","text":"

This page describes FireFly's versioning scheme

"},{"location":"contributors/version_scheme/#semantic-versioning","title":"Semantic versioning","text":"

FireFly follows semantic versioning. In summary, this means:

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards compatible manner, and
  • PATCH version when you make backwards compatible bug fixes.
  • Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

When creating a new release, the release name and tag should be the semantic version should be prefixed with a v . For example, a certain release name/tag could be v0.9.0.

"},{"location":"contributors/version_scheme/#pre-release-test-versions","title":"Pre-release test versions","text":"

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 v0.9.0 and today's date is October 22, 2021, the version name/tag would be: v0.9.0-20211022-01. 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 v0.9.0-20211022-02.

"},{"location":"contributors/version_scheme/#candidate-releases","title":"Candidate releases","text":"

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 v0.9.0 but we want to create an alpha release for 1.0, the release name/tag would be v1.0.0-alpha.1.

"},{"location":"faqs/","title":"FAQs","text":"

Find answers to the most commonly asked FireFly questions.

"},{"location":"faqs/#how-does-firefly-enable-multi-chain-applications","title":"How does FireFly enable multi-chain applications?","text":"

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.

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.

"},{"location":"faqs/#how-do-i-deploy-smart-contracts","title":"\ud83d\udcdc How do I deploy smart contracts?","text":"

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.

For Fabric networks, please refer to the Fabric chaincode lifecycle docs for detailed instructions on how to deploy and manage Fabric chaincode.

"},{"location":"faqs/#can-i-connect-firefly-to-metamask","title":"\ud83e\udd8a Can I connect FireFly to MetaMask?","text":"

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.

"},{"location":"faqs/#connect-with-us-on-discord","title":"\ud83d\ude80 Connect with us on Discord","text":"

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 firefly channel:

"},{"location":"gettingstarted/","title":"Getting Started","text":"

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!

"},{"location":"gettingstarted/#what-you-will-accomplish-with-this-guide","title":"What you will accomplish with this guide","text":"

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.

"},{"location":"gettingstarted/#were-here-to-help","title":"We're here to help!","text":"

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.

"},{"location":"gettingstarted/#get-started-install-the-firefly-cli","title":"Get started: Install the FireFly CLI","text":"

Now that you've got the FireFly CLI set up on your machine, the next step is to create and start a FireFly stack.

\u2460 Install the FireFly CLI \u2192

"},{"location":"gettingstarted/firefly_cli/","title":"Install the FireFly CLI","text":""},{"location":"gettingstarted/firefly_cli/#prerequisites","title":"Prerequisites","text":"

In order to run the FireFly CLI, you will need a few things installed on your dev machine:

  • Docker
  • Docker Compose
  • openssl
"},{"location":"gettingstarted/firefly_cli/#linux-users","title":"Linux Users","text":"

NOTE: For Linux users, it is recommended that you add your user to the docker group so that you do not have to run ff or docker as root or with sudo. For more information about Docker permissions on Linux, please see Docker's documentation on the topic.

"},{"location":"gettingstarted/firefly_cli/#windows-users","title":"Windows Users","text":"

NOTE: For Windows users, we recommend that you use Windows Subsystem for Linux 2 (WSL2). Binaries provided for Linux will work in this environment.

"},{"location":"gettingstarted/firefly_cli/#install-the-cli","title":"Install the CLI","text":"

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.

"},{"location":"gettingstarted/firefly_cli/#download-the-package-for-your-os","title":"Download the package for your OS","text":"

Go to the latest release page and download the package for your OS and CPU architecture.

"},{"location":"gettingstarted/firefly_cli/#extract-the-binary-and-move-it-to-usrbinlocal","title":"Extract the binary and move it to /usr/bin/local","text":"

Assuming you downloaded the package from GitHub into your Downloads directory, run the following command:

sudo tar -zxf ~/Downloads/firefly-cli_*.tar.gz -C /usr/local/bin ff && rm ~/Downloads/firefly-cli_*.tar.gz\n

If you downloaded the package from GitHub into a different directory, you will need to change the tar command above to wherever the firefly-cli_*.tar.gz file is located.

"},{"location":"gettingstarted/firefly_cli/#macosusers","title":"macOSUsers","text":"

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.

"},{"location":"gettingstarted/firefly_cli/#alternative-installation-method-install-via-go","title":"Alternative installation method: Install via Go","text":"

If you have a local Go development environment, and you have included ${GOPATH}/bin in your path, you could also use Go to install the FireFly CLI by running:

go install github.com/hyperledger/firefly-cli/ff@latest\n
"},{"location":"gettingstarted/firefly_cli/#verify-the-installation","title":"Verify the installation","text":"

After using either installation method above, you can verify that the CLI is successfully installed by running ff version. This should print the current version like this:

{\n  \"Version\": \"v0.0.47\",\n  \"License\": \"Apache-2.0\"\n}\n
"},{"location":"gettingstarted/firefly_cli/#next-steps-start-your-environment","title":"Next steps: Start your environment","text":"

Now that you've got the FireFly CLI set up on your machine, the next step is to create and start a FireFly stack.

\u2461 Start your environment \u2192

"},{"location":"gettingstarted/sandbox/","title":"Use the Sandbox","text":""},{"location":"gettingstarted/sandbox/#previous-steps-start-your-environment","title":"Previous steps: Start your environment","text":"

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.

\u2190 \u2461 Start your environment

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.

"},{"location":"gettingstarted/sandbox/#video-walkthrough","title":"Video walkthrough","text":"

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.

"},{"location":"gettingstarted/sandbox/#open-the-firefly-sandbox-for-the-first-member","title":"Open the FireFly Sandbox for the first member","text":"

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

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
"},{"location":"gettingstarted/sandbox/#sandbox-layout","title":"Sandbox Layout","text":"

The Sandbox is split up into three columns:

"},{"location":"gettingstarted/sandbox/#left-column-prepare-your-request","title":"Left column: Prepare your request","text":"

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.

The first tab we will explore is the MESSAGING tab. This is where we can send broadcasts and private messages.

"},{"location":"gettingstarted/sandbox/#middle-column-preview-server-code-and-see-response","title":"Middle column: Preview server code and see response","text":"

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 RUN button to actually send the request.

"},{"location":"gettingstarted/sandbox/#right-column-events-received-on-the-websocket","title":"Right column: Events received on the WebSocket","text":"

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.

"},{"location":"gettingstarted/sandbox/#messages","title":"Messages","text":"

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.

"},{"location":"gettingstarted/sandbox/#things-to-try-out","title":"Things to try out","text":"
  • Send a broadcast message and view the data payload in every member's FireFly Explorer
  • Send a private message to one member, and verify that the data payload is not visible in the third member's FireFly Explorer
  • Send an image file and download it from another member's FireFly Explorer
"},{"location":"gettingstarted/sandbox/#tokens","title":"Tokens","text":"

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.

"},{"location":"gettingstarted/sandbox/#things-to-try-out_1","title":"Things to try out","text":"
  • Create a fungible token pool and mint some tokens and view your balance in the FireFly Explorer
  • Transfer some amount of those tokens to another member and view the transfer transaction in the FireFly Explorer
  • Burn some amount of tokens and view the transaction and updated balances in the FireFly Explorer
  • Create a non-fungible token pool and mint some NFTs
  • Transfer an NFT to another member and verify the account balances in the FireFly Explorer
"},{"location":"gettingstarted/sandbox/#contracts","title":"Contracts","text":"

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.

"},{"location":"gettingstarted/sandbox/#things-to-try-out_2","title":"Things to try out","text":"
  • Create a contract interface and API, then view the Swagger UI for your new API
  • Create an event listener
  • 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.
"},{"location":"gettingstarted/sandbox/#go-forth-and-build","title":"Go forth and build!","text":"

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.

"},{"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":"

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.

\u2190 \u2460 Install the FireFly CLI

Now that you have the FireFly CLI installed, you are ready to run some Supernodes on your machine!

"},{"location":"gettingstarted/setup_env/#a-firefly-stack","title":"A FireFly Stack","text":"

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.

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.

"},{"location":"gettingstarted/setup_env/#system-resources","title":"System Resources","text":"

The FireFly stack will run in a docker-compose 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.

"},{"location":"gettingstarted/setup_env/#creating-a-new-stack","title":"Creating a new stack","text":"

It's really easy to create a new FireFly stack. The ff init 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.

To create an Ethereum based stack, run:

ff init ethereum\n

To create an Fabric based stack, run:

ff init fabric\n

Choose a stack name. For this guide, I will choose the name dev, but you can pick whatever you want:

stack name: dev\n

Chose the number of members for your stack. For this guide, we should pick 3 members, so we can try out both public and private messaging use cases:

number of members: 3\n

"},{"location":"gettingstarted/setup_env/#stack-initialization-options","title":"Stack initialization options","text":"

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 ff init ethereum --help or to see the full list of Fabric options run ff init fabric --help

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
"},{"location":"gettingstarted/setup_env/#start-your-stack","title":"Start your stack","text":"

To start your stack simply run:

ff start dev\n

This may take a minute or two and in the background the FireFly CLI will do the following for you:

  • Download Docker images for all of the components of the Supernode
  • Initialize a new blockchain and blockchain node running inside a container
  • Set up configuration between all the components
  • Deploy FireFly's BatchPin smart contract
  • Deploy an ERC-1155 token smart contract
  • Register an identity for each member and node

NOTE: For macOS users, the default port (5000) is already in-use by ControlCe service (AirPlay Receiver). You can either disable this service in your environment, or use a different port when creating your stack (e.g. ff init dev -p 8000)

After your stack finishes starting it will print out the links to each member's UI and the Sandbox for that node:

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
"},{"location":"gettingstarted/setup_env/#next-steps-use-in-the-sandbox","title":"Next steps: Use in the Sandbox","text":"

Now that you have some Supernodes running, it's time to start playing: in the Sandbox!

\u2462 Use the Sandbox \u2192

"},{"location":"overview/gateway_features/","title":"Web3 Gateway Features","text":"

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.

"},{"location":"overview/gateway_features/#transfer-tokenized-value","title":"Transfer tokenized value","text":"

The Digital Asset Features allow you to connect to token economies, in multiple blockchains, using the same infrastructure and signing keys.

The complexities of how each token works, and how each blockchain works, are abstracted away from you by the Hyperledger FireFly Connector Framework.

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.

"},{"location":"overview/gateway_features/#invoke-any-other-type-of-smart-contract","title":"Invoke any other type of smart contract","text":"

The API Generation features of Hyperledger FireFly, allow you to generate a convenient and reliable REST API for any smart contract logic.

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.

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.

  • Handles peaks in workload, drip-feeding transactions onto the chain
  • Handles large batch submissions, tracking
  • Manages nonce assignment at high volume
  • Idempotent APIs assuring that business transactions are submitted exactly once

For EVM based chains, these features were significantly enhanced in the new EVMConnect connector introduced in v1.1 of FireFly (superseding EthConnect).

"},{"location":"overview/gateway_features/#index-data-from-the-blockchain","title":"Index data from the blockchain","text":"

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.

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.

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.

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.

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.

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.

"},{"location":"overview/gateway_features/#reliably-trigger-events-in-your-applications","title":"Reliably trigger events in your applications","text":"

One of the most important universal rules about Web3 applications, is that they are event-driven.

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.

This means the integration into your application and core systems needs to be event-driven too.

The same features that support reliable indexing of the blockchain data, allow reliable triggering of application code, business workflows, and core system integrations.

Learn more about the FireFly Event Bus

"},{"location":"overview/gateway_features/#manage-decentralized-data-nfts-etc","title":"Manage decentralized data (NFTs etc.)","text":"

Your blockchain transactions are likely to refer to data that is stored off-chain.

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.

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.

Structured JSON data can be stored, uploaded and downloaded from the FireFly database.

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.

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.

"},{"location":"overview/gateway_features/#maintain-a-private-address-book","title":"Maintain a private address book","text":"

You need to manage your signing keys, and know the signing keys of others you are transacting with. A blockchain address like 0x0742e81393ee79C768e84cF57F1bF314F0f31ECe is not very helpful for this.

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.

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.

Learn more about Hyperledger FireFly Identities

"},{"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":"

A separate choice to the technology for your blockchain, is what combination of blockchain ecosystems you will integrate with.

There are a huge variety of options, and increasingly you might find yourself integrating with multiple ecosystems in your solutions.

A rough (and incomplete) high level classification of the blockchains available is as follows:

  • Layer 1 public blockchains
  • This is where most token ecosystems are rooted
  • Layer 2 public scaling solutions backed by a Layer 1 blockchain
  • These are increasing where transaction execution takes place that needs to be reflected eventually back to a Layer 1 blockchain (due to cost/congestion in the Layer 1 chains)
  • Permissioned side-chains
  • Historically this has been where the majority of production adoption of enterprise blockchain has focussed, due to the predictable cost, performance, and ability to manage the validator set and boundary API security alongside a business network governance policy
  • These might have their state check-pointed/rolled-up to a Layer 2 or Layer 1 chain

The lines are blurring between these categorizations as the technologies and ecosystems evolve.

"},{"location":"overview/public_vs_permissioned/#public-blockchain-variations","title":"Public blockchain variations","text":"

For the public Layer 1 and 2 solutions, there are too many subclassifications to go into in detail here:

  • Whether ecosystems supports custom smart contract execution (EVM based is most common, where contracts are supported)
  • What types of token standards are supported, or other chain specific embedded smart contracts
  • Whether the chain follows an unspent transaction output (UTXO) or Account model
  • How value is bridged in-to / out-of the ecosystem
  • How the validator set of the chain is established - most common is Proof of Stake (PoS)
  • How data availability is maintained - to check the working of the validators ensure the historical state is not lost
  • The consensus algorithm, and how it interacts with the consensus of other blockchains
  • How state in a Layer 2 is provable in a parent Layer 1 chain (rollup technologies etc.)
"},{"location":"overview/public_vs_permissioned/#common-public-considerations","title":"Common public considerations","text":"

The thing most consistent across public blockchain technologies, is that the technical decisions are backed by token economics.

Put simply, creating a system where it's more financially rewarding to behave honestly, than it is to subvert and cheat the system.

This means that participation costs, and that the mechanisms needed to reliably get your transactions into these systems are complex. Also that the time it might take to get a transaction onto the chain can be much longer than for a permissioned blockchain, with the potential to have to make a number of adjustments/resubmissions.

The choice of whether to run your own node, or use a managed API, to access these blockchain ecosystems is also a factor in the behavior of the transaction submission and event streaming.

"},{"location":"overview/public_vs_permissioned/#firefly-architecture-for-public-chains","title":"FireFly architecture for public chains","text":"

One of the fastest evolving aspects of the Hyperledger FireFly ecosystem, is how it facilitates enterprises to participate in these.

The architecture is summarized as follows:

  • New FireFly Transaction Manager runtime
  • Operates as a microservice extension of the FireFly Core
  • Uses the operation resource within FireFly Core to store and update state
  • Runs as a singleton and is responsible for nonce assignment
  • Takes as much heavy lifting away from blockchain specific connectors as possible
  • Lightweight FireFly Connector API (ffcapi)
  • Simple synchronous RPC operations that map to the most common operations supported across public blockchain technologies
  • Examples:
    • Find the next nonce for a given signing key
    • Serialize a transaction from a set of JSON inputs and an interface definition
    • Submit an un-signed transaction with a given gas price to the blockchain, via a signing wallet
    • Establish a new block listener
    • Poll for new blocks
    • Establish a new event log listener
    • Poll for new events
  • Pluggable Policy Engine
  • Invoked to make decisions on transaction submission
  • Responsible for gas price calculation
  • Able to intervene and adjust the characteristics of signing/submission
  • OSS reference implementation provided with Gas Station REST API integration
  • Confirmation Manager
  • Extracted from the Ethconnect codebase
  • Coupled to both transaction submission and event confirmation
  • Embeds an efficient block cache
  • Event Streams
  • Extracted from the Ethconnect codebase
  • Checkpoint restart based reliable at-least-once delivery of events
  • WebSockets interface upstream to FireFly Core

This evolution involves a significant refactoring of components used for production solutions in the FireFly Ethconnect microservice since mid 2018. This was summarized in firefly-ethconnect#149, and cumulated in the creation of a new repository in 2022.

You can follow the progress and contribute in this repo: https://github.com/hyperledger/firefly-transaction-manager

"},{"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":"

Hyperledger FireFly is an organization's gateway to Web3, including all the blockchain ecosystems that they participate in.

Multiple blockchains, multiple token economies, and multiple business networks.

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:

  • Public Blockchains, Layer 2 scaling solutions, Side chains, and App chains
  • Permissioned Blockchains and Distributed Ledger Technologies (DLTs)
  • Decentralized storage solutions
  • Token ecosystems and standards
  • Smart Contracts, DeFi solutions and DAOs
  • Private off-chain encrypted communication rails
  • Advanced cryptography solutions
  • Identity frameworks
"},{"location":"overview/supernode_concept/#an-open-source-supernode-for-web3-apps","title":"An Open Source Supernode for Web3 Apps","text":"

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.

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.

We call this a Supernode - it sits between the application and the underlying infrastructure nodes, providing layers of additional function.

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.

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.

"},{"location":"overview/usage_patterns/","title":"Usage Patterns","text":"

There are two modes of usage for Hyperledger Firefly: Web3 Gateway and Multiparty

A single runtime can operate in both of these modes, using different namespaces.

"},{"location":"overview/usage_patterns/#web3-gateway-mode","title":"Web3 Gateway Mode","text":"

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.

In this mode you can:

  • Transfer tokenized value
  • Invoke any other type of smart contract
  • Index data from the blockchain
  • Reliably trigger events in your applications and back-office core systems
  • Manage decentralized data (NFTs etc.)
  • Use a private address book to manage signing identities and relationships
  • ... and much more

Learn more about Web3 Gateway Mode.

"},{"location":"overview/usage_patterns/#multiparty-mode","title":"Multiparty Mode","text":"

Multiparty mode is used to build multi-party systems, with a common application runtime deployed by each enterprise participant.

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.

In this mode you can do everything you could do in Web3 Gateway mode, plus:

  • Share and enforce common data formats
  • Exchange data privately, via an encrypted data bus
  • Structured JSON data payloads
  • Large documents
  • Coordinate on-chain and off-chain data exchange
  • Private data
  • Broadcast data
  • Mask on-chain activities using hashes
  • Use a shared address book to manage signing identities and relationships
  • ... and much more

Learn more about Multiparty Mode.

"},{"location":"overview/key_components/","title":"Key Features","text":"

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.

"},{"location":"overview/key_components/apps/","title":"Apps","text":""},{"location":"overview/key_components/apps/#apps","title":"Apps","text":"

Rapidly accelerating development of applications is a key feature of Hyperledger FireFly.

The toolkit is designed to support the full-stack of applications in the enterprise Web3 ecosystem, not just the Smart Contract layer.

Business logic APIs, back-office system integrations, and web/mobile user experiences are just as important to the overall Web3 use case.

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.

"},{"location":"overview/key_components/apps/#api-gateway","title":"API Gateway","text":"

FireFly provides APIs that:

  • Are fast and efficient
  • Have rich query support
  • Give deterministic outcomes and clear instructions for safe use
  • Integrate with your security frameworks like OAuth 2.0 / OpenID Connect single sign-on
  • Provide Open API 3 / Swagger definitions
  • Come with code SDKs, with rich type information
  • Conform as closely as possible to the principles of REST
  • Do not pretend to be RESTful in cases when it is impossible to be

Learn more about deploying APIs for custom smart contracts in this tutorial

"},{"location":"overview/key_components/apps/#event-streams","title":"Event Streams","text":"

The reality is that the only programming paradigm that works for a decentralized solutions, is an event-driven one.

All blockchain technologies are for this reason event-driven programming interfaces at their core.

In an overall solution, those on-chain events must be coordinated with off-chain private data transfers, and existing core-systems / human workflows.

This means great event support is a must:

  • Convenient WebSocket APIs that work for your microservices development stack
  • Support for Webhooks to integrated serverless functions
  • Integration with your core enterprise message queue (MQ) or enterprise service bus (ESB)
  • At-least-once delivery assurance, with simple instructions at the application layer

Learn all about the Hyperledger FireFly Event Bus, and event-driven application architecture, in this reference section

"},{"location":"overview/key_components/apps/#api-generation","title":"API Generation","text":"

The blockchain is going to be at the heart of your Web3 project. While usually small in overall surface area compared to the lines of code in the traditional application tiers, this kernel of mission-critical code is what makes your solution transformational compared to a centralized / Web 2.0 solution.

Whether the smart contract is hand crafted for your project, an existing contract on a public blockchain, or a built-in pattern of a framework like FireFly - it must be interacted with correctly.

So there can be no room for misinterpretation in the hand-off between the blockchain Smart Contract specialist, familiar with EVM contracts in Solidity/Vyper, Fabric chaincode (or maybe even raw block transition logic in Rust or Go), and the backend / full-stack application developer / core-system integrator.

Well documented APIs are the modern norm for this, and it is no different for blockchain.

This means Hyperledger FireFly provides:

  • Generating the interface for methods and events on your smart contract
  • Providing robust transaction submission, and event streaming
  • Publishing the API, version, and location, of your smart contracts to the network
"},{"location":"overview/key_components/connectors/","title":"Connector Framework","text":""},{"location":"overview/key_components/connectors/#pluggable-microservices-architecture","title":"Pluggable Microservices Architecture","text":"

The ability for every component to be pluggable is at the core of Hyperledger FireFly.

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.

"},{"location":"overview/key_components/connectors/#extension-points","title":"Extension points","text":"
  • Blockchain - a rich framework for extensibility to any blockchain / digital ledger technology (DLT)
  • Tokens - mapping token standards and governance models to a common data model
  • Shared storage - supporting permissioned and public distributed storage technologies
  • Data exchange - private local/storage and encrypted transfer of data
  • Identity - flexibility for resolving identities via Decentralized IDentifier (DID)
  • Persistence - the local private database

Learn more about the plugin architecture here

"},{"location":"overview/key_components/connectors/#blockchain-connector-framework","title":"Blockchain Connector Framework","text":"

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.

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.

Check out instructions to connect to a list of remote blockchain networks here.

Find out more about the Blockchain Connector Framework here.

"},{"location":"overview/key_components/digital_assets/","title":"Digital Assets","text":""},{"location":"overview/key_components/digital_assets/#digital-asset-features","title":"Digital asset features","text":"

The modelling, transfer and management of digital assets is the core programming foundation of blockchain.

Yet out of the box, raw blockchains designed to efficiently manage these assets in large ecosystems, do not come with all the building blocks needed by applications.

"},{"location":"overview/key_components/digital_assets/#token-api","title":"Token API","text":"

Token standards have been evolving in the industry through standards like ERC-20/ERC-721, and the Web3 signing wallets that support these.

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.

This means one application or set of back-end systems, can integrate with multiple blockchains, and different token implementations.

Pluggability here is key, so that the rules of governance of each digital asset ecosystem can be exposed and enforced. Whether tokens are fungible, non-fungible, or some hybrid in between.

Learn more about token standards for fungible tokens, and non-fungible tokens (NFTs) in this set of tutorials

"},{"location":"overview/key_components/digital_assets/#transfer-history-audit-trail","title":"Transfer history / audit trail","text":"

For efficiency blockchains do not provide a direct ability to query historical transaction information.

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.

So off-chain indexing of transaction history is an absolute must-have for any digital asset solution.

Hyperledger FireFly provides:

  • Automatic indexing of tokens, whether existing or newly deployed
  • Off-chain indexing of fungible and non-fungible asset transfers & balances
  • Off-chain indexing of approvals
  • Integration with digital identity
  • Full extensibility across both token standards and blockchain technologies
"},{"location":"overview/key_components/digital_assets/#wallets","title":"Wallets","text":"

Wallet and signing-key management is a critical requirement for any blockchain solution, particularly those involving the transfer of digital assets between wallets.

Hyperledger FireFly provides you the ability to:

  • Integrate multiple different signing/custody solutions in a proven way
  • Manage the mapping of off-chain identities to on-chain signing identities
  • Provide a plug-point for policy-based decision making on high value transactions
  • Manage connections to multiple different blockchain solutions
"},{"location":"overview/key_components/flows/","title":"Flows","text":""},{"location":"overview/key_components/flows/#data-flow","title":"Data flow","text":"

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.

Some additional data flow is always required. This does not diminish the value of executing the kernel of the logic within the blockchain itself.

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.

Let's look at a few common examples:

"},{"location":"overview/key_components/flows/#digital-asset-transfers","title":"Digital Asset Transfers","text":"

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.

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?

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.

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.

A common form of digital escrow is a Hashed Timelock Contract (HTLC).

"},{"location":"overview/key_components/flows/#non-fungible-tokens-nfts-and-hash-pinning","title":"Non-fungible Tokens (NFTs) and hash-pinning","text":"

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.

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.

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.

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.

"},{"location":"overview/key_components/flows/#dynamic-nfts-and-business-transaction-flow","title":"Dynamic NFTs and Business Transaction Flow","text":"

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.

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.

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.

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.

"},{"location":"overview/key_components/flows/#data-and-transaction-flow-patterns","title":"Data and Transaction Flow patterns","text":"

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.

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:

  • Coordinating the transfer of data off-chain with a blockchain sequencing transaction
  • Batching for high throughput transfer via the blockchain and distributed storage technologies
  • Managing privacy groups between parties involved in a business transaction
  • Masking the relationship between blockchain transactions, for sensitive data

Learn more in Multiparty Process Flows

"},{"location":"overview/key_components/orchestration_engine/","title":"Orchestration Engine","text":""},{"location":"overview/key_components/orchestration_engine/#firefly-core","title":"FireFly Core","text":"

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.

"},{"location":"overview/key_components/orchestration_engine/#data-layer","title":"Data Layer","text":"

Your own private view of the each network you connect:

  • Indexes of all tokens and NFTs that you transact with
  • A consistent view across multiple blockchains
  • High performance rich query of transaction and data audit trail
  • Private data you have received from other parties
  • Local copies of data you have download from IPFS or other shared storage tech
"},{"location":"overview/key_components/orchestration_engine/#event-bus","title":"Event Bus","text":"

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:

Decentralized applications are event-driven.

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.

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.

  • Token transfer events, across multiple blockchains, and varied asset types
  • Custom smart contract events
  • Correlated on-chain and off-chain data events

Learn more about the event bus and event-driven programming in this reference document

"},{"location":"overview/key_components/security/","title":"Security","text":""},{"location":"overview/key_components/security/#api-security","title":"API Security","text":"

Hyperledger FireFly provides a pluggable infrastructure for authenticating API requests.

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.

A reference plugin implementation is provided for HTTP Basic Auth, combined with a htpasswd verification of passwords with a bcrypt encoding.

See this config section for details, and the reference implementation in Github

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.

"},{"location":"overview/key_components/security/#data-partitioning-and-tenancy","title":"Data Partitioning and Tenancy","text":"

Namespaces also provide a data isolation system for different applications / teams / tenants sharing a Hyperledger FireFly node.

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.

"},{"location":"overview/key_components/security/#private-data-exchange","title":"Private Data Exchange","text":"

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 & documents.

A reference microservice implementation is provided for HTTPS point-to-point connectivity with mutual TLS encryption.

See the reference implementation in Github

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.

Learn more about these private data flows in Multiparty Process Flows.

"},{"location":"overview/key_components/tools/","title":"Tools","text":""},{"location":"overview/key_components/tools/#firefly-cli","title":"FireFly CLI","text":"

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.

"},{"location":"overview/key_components/tools/#firefly-sandbox","title":"FireFly Sandbox","text":"

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.

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

"},{"location":"overview/key_components/tools/#firefly-explorer","title":"FireFly Explorer","text":"

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.

"},{"location":"overview/multiparty/","title":"Enterprise multi-party systems","text":""},{"location":"overview/multiparty/#introduction","title":"Introduction","text":"

Multiparty mode has all the features in Gateway mode with the added benefit of multi-party process flows.

A multi-party system is a class of application empowered by the technology revolution of blockchain digital ledger technology (DLT), and emerging cryptographic proof technologies like zero-knowledge proofs (ZKPs) and trusted execution environments (TEEs).

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.

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.

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.

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.

"},{"location":"overview/multiparty/#points-of-difference","title":"Points of difference","text":"

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.

Multi-party systems are different from centralized third-party systems, because each party retains sovereignty over:

  • Their application instance
  • Their private data
  • Their business processes
  • Their proprietary business logic
  • Their internal business processes and IT controls
"},{"location":"overview/multiparty/#use-case-example","title":"Use Case Example","text":"

There are many multiparty use cases. An example for healthcare is detailed below.

Patient care requires multiple entities to work together including healthcare providers, insurance companies, and medical systems. Sharing data between these parties is inefficient and prone to errors and patient information must be kept secure and up to date. Blockchain's shared ledger makes it possible to automate data sharing while ensuring accuracy and privacy.

In a Multi-party FireFly system, entities are able to share data privately as detailed in the \"Data Exchange\" section. For example, imagine a scenario where there is 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.

In a larger healthcare ecosystem with many members, a similar concept may emerge with multiple variations of members.

"},{"location":"overview/multiparty/broadcast/","title":"Broadcast / shared data","text":""},{"location":"overview/multiparty/broadcast/#introduction","title":"Introduction","text":"

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

"},{"location":"overview/multiparty/broadcast/#blockchain-backed-broadcast","title":"Blockchain backed broadcast","text":"

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.

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.

For more information see Multiparty Event Sequencing.

"},{"location":"overview/multiparty/broadcast/#shared-data","title":"Shared data","text":"

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.

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.

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.

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.

"},{"location":"overview/multiparty/broadcast/#firefly-built-in-broadcasts","title":"FireFly built-in broadcasts","text":"

FireFly uses the broadcast mechanism internally to distribute key information to all parties in the network:

  • Network map
  • Organizational identities
  • Nodes
  • See Identities in the reference section for more information
  • Datatype definitions
  • See Datatype in the reference section for more information
  • Namespaces
  • See Namespaces for more information

These definitions rely on the same assurances provided by blockchain backed broadcast that FireFly applications do.

  • Verification of the identity of the party in the network that performed the broadcast
  • Deterministic assignment of a namespace+name to an unique item of data
  • 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)
"},{"location":"overview/multiparty/data_exchange/","title":"Private data exchange","text":""},{"location":"overview/multiparty/data_exchange/#introduction","title":"Introduction","text":"

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.

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.

So real-time application to application private messaging, and private transfer of large blobs/documents, are first class constructs in the FireFly API.

"},{"location":"overview/multiparty/data_exchange/#qualities-of-service","title":"Qualities of service","text":"

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.

  • Transport Encryption
  • 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.
  • Authentication
  • 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.
  • 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).
  • Request/Response (Sync) vs. Message Queuing (Async)
  • 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.
  • 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.
  • Hub & spoke vs. Peer to peer
  • 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.
  • End-to-end Payload Encryption
  • 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.
  • Large blob / Managed file transfer
  • 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.
"},{"location":"overview/multiparty/data_exchange/#firefly-oss-implementation","title":"FireFly OSS implementation","text":"

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.

See hyperledger/firefly-dataexchange-https

"},{"location":"overview/multiparty/deterministic/","title":"Deterministic Compute","text":""},{"location":"overview/multiparty/deterministic/#introduction","title":"Introduction","text":"

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.

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.

The more sophisticated the agreement is you want to prove, the more consideration needs to be taken into factors such as:

  • Data privacy
  • Data deletion
  • Ease of understanding by business users
  • Ease of audit
  • Autonomy of parties with proprietary business logic
  • Human workflows (obviously non-deterministic)
  • Technology complexity/maturity (particularly for privacy preserving technologies)
  • Cost and skills for implementation

FireFly embraces the fact that different use cases, will make different decisions on how much of the agreement should be enforced through deterministic compute.

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.

"},{"location":"overview/multiparty/deterministic/#the-fundamental-building-blocks","title":"The fundamental building blocks","text":"

There are some fundamental types of deterministic computation, that can be proved with mature blockchain technology, and all multi-party systems should consider exploiting:

  • Total conservation of value
  • Allows you to assign value to something, because you know it is a fraction of a total pool
  • This is the magic behind fungible tokens, or \"coins\"
  • The proven technology for this is a shared ledger of all previous transactions
  • Learn more in the Tokens section
  • Existence and ownership of a unique identifiable thing
  • Gives you an anchor to attach to something in the real world
  • This is the magic behind non-fungible tokens (NTFs)
  • The proven technology for this is a shared ledger of its creation, and ownership changes
  • Learn more in the Tokens section
  • An agreed sequence of events
  • The foundation tool that allows the building of higher level constructs (including tokens)
  • Not previously available when business ecosystems used HTTP/Messaging transports alone
  • Can be bi-lateral, multi-lateral or global
  • Each blockchain technology has different features to establish these \"chains\" of information
  • Different approaches provide privacy different levels of privacy on the parties and sequence
  • Identification of data by a \"hash\" of its contents
  • The glue that binds a piece of private data, to a proof that you have a copy of that data
  • This is the basis of \"pinning\" data to the blockchain, without sharing its contents
  • Care needs to be taken to make sure the data is unique enough to make the hash secure
  • Learn more in the Gateway Features section
"},{"location":"overview/multiparty/deterministic/#advanced-cryptography-and-privacy-preserving-trusted-compute","title":"Advanced Cryptography and Privacy Preserving Trusted Compute","text":"

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.

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.

Technologies exist that can solve these requirements, with two major categories:

  • Zero Knowledge Proofs (ZKPs)
  • 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.
  • Trusted Compute Environments (TEEs)
  • 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.

FireFly today provides an orchestration engine that's helpful in coordinating the inputs, outputs, and execution of such advanced cryptography technologies.

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.

"},{"location":"overview/multiparty/deterministic/#complementary-approaches-to-deterministic-computation","title":"Complementary approaches to deterministic computation","text":"

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.

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.

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.

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.

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.

"},{"location":"overview/multiparty/multiparty_flow/","title":"Multiparty Process Flows","text":""},{"location":"overview/multiparty/multiparty_flow/#flow-features","title":"Flow features","text":"

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.

"},{"location":"overview/multiparty/multiparty_flow/#private-data-flow","title":"Private data flow","text":"

Managing the flows of data so that the right information is shared with the right parties, at the right time, means thinking carefully about what data flows over what channel.

The number of enterprise solutions where all data can flow directly through the blockchain, is vanishingly small.

Coordinating these different data flows is often one of the biggest pieces of heavy lifting solved on behalf of the application by a robust framework like FireFly:

  • Establishing the identity of participants so data can be shared
  • Securing the transfer of data off-chain
  • Coordinating off-chain data flow with on-chain data flow
  • Managing sequence for deterministic outcomes for all parties
  • Integrating off-chain private execution with multi-step stateful business logic
"},{"location":"overview/multiparty/multiparty_flow/#multi-party-business-process-flow","title":"Multi-party business process flow","text":"

Web3 has the potential to transform how ecosystems interact. Digitally transforming legacy process flows, by giving deterministic outcomes that are trusted by all parties, backed by new forms of digital trust between parties.

Some of the most interesting use cases require complex multi-step business process across participants. The Web3 version of business process management, comes with a some new challenges.

So you need the platform to:

  • Provide a robust event-driven programming model fitting a \"state machine\" approach
  • Integrate with the decentralized application stack of each participant
  • Allow integration with the core-systems and human decision making of each participant
  • Provide deterministic ordering between all parties
  • Provide identity assurance and proofs for data flow / transition logic
"},{"location":"overview/multiparty/multiparty_flow/#data-exchange","title":"Data exchange","text":"

Business processes need data, and that data comes in many shapes and sizes.

The platform needs to handle all of them:

  • Large files and documents, as well as application data
  • Uniqueness / Enterprise NFTs - agreement on a single \"foreign key\" for a record
  • Non-repudiation, and acknowledgement of receipt
  • Coordination of flows of data, with flows of value - delivery vs. payment scenarios
"},{"location":"overview/multiparty/multiparty_flow/#building-multi-party-flows","title":"Building multi-party flows","text":"

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.

  • Build multi-party business processes where there is one agreed outcome:
  • Agree the trigger, inputs, outputs of each step in the process
  • Agree any common \"rules of the road\" must be adhered to
  • Look back at your shared history, when deciding to commit to the next step:
  • Fast rich-query cache, backed by a private database
  • Initiate the next step through automated or manual decision making
  • Only consider a step final once it's multi-party sequence has been confirmed
  • Gain big efficiencies in how multi-party business processes work:
  • Once locked in, a step is consider final - attested to by the party
  • If two parties submit conflicting actions, one wins, and one loses
  • Avoids complex compensation logic in the business orchestration layer
  • Provides one clear source of truth to quickly resolve multi-party disputes
  • Program multi-party apps using the tools you know:
  • REST APIs for triggering the next step in a process, and querying history
  • WebSockets and Webhooks for events (pluggable to other event transports)
  • Remember - each party runs their own copy of the app, with their own private data
  • Allow each party to integrate into their existing core systems:
  • Realtime or batch
  • Human workflows
  • Proprietary business logic that is unique to one party
  • Avoid sensitive data written to the blockchain:
  • Works in bi-lateral and multi-lateral scenarios
  • Designed to limit leaking other \"metadata\" about the transaction as well
  • Share partial history with different participants in a
  • No requirement to write custom on-chain smart contract logic:
  • Can be combined with rich custom on-chain logic as well
"},{"location":"overview/multiparty/multiparty_flow/#innovate-fast","title":"Innovate fast","text":"

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.

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.

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.

"},{"location":"overview/multiparty/multiparty_flow/#consider-the-on-chain-toolbox-too","title":"Consider the on-chain toolbox too","text":"

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.

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.

On top of this you can add advanced tools like digital escrow, signature / threshold based voting on outcomes, and atomic swaps of value/ownership.

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.

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.

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.

Learn more in the Deterministic Compute section.

"},{"location":"reference/api_post_syntax/","title":"API POST Syntax","text":""},{"location":"reference/api_post_syntax/#syntax-overview","title":"Syntax Overview","text":"

Endpoints that allow submitting a transaction allow an optional query parameter called confirm. When confirm=true 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.

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.

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.

"},{"location":"reference/api_post_syntax/#example-api-call","title":"Example API Call","text":"

POST /api/v1/messages/broadcast?confirm=true

This will broadcast a message and wait for the message to be confirmed before returning.

"},{"location":"reference/api_query_syntax/","title":"API Query Syntax","text":""},{"location":"reference/api_query_syntax/#syntax-overview","title":"Syntax Overview","text":"

REST collections provide filter, skip, limit and sort support.

  • The field in the message is used as the query parameter
  • Syntax: field=[modifiers][operator]match-string
  • When multiple query parameters are supplied these are combined with AND
  • When the same query parameter is supplied multiple times, these are combined with OR
"},{"location":"reference/api_query_syntax/#example-api-call","title":"Example API Call","text":"

GET /api/v1/messages?confirmed=>0&type=broadcast&topic=t1&topic=t2&context=@someprefix&sort=sequence&descending&skip=100&limit=50

This states:

  • Filter on confirmed greater than 0
  • Filter on type exactly equal to broadcast
  • Filter on topic exactly equal to t1 or t2
  • Filter on context containing the case-sensitive string someprefix
  • Sort on sequence in descending order
  • Paginate with limit of 50 and skip of 100 (e.g. get page 3, with 50/page)

Table of filter operations, which must be the first character of the query string (after the = in the above URL path example)

"},{"location":"reference/api_query_syntax/#operators","title":"Operators","text":"

Operators are a type of comparison operation to perform against the match string.

Operator Description = Equal (none) Equal (shortcut) @ Containing ^ Starts with $ Ends with << Less than < Less than (shortcut) <= Less than or equal >> Greater than > Greater than (shortcut) >= Greater than or equal

Shortcuts are only safe to use when your match string starts with a-z, A-Z, 0-9, - or _.

"},{"location":"reference/api_query_syntax/#modifiers","title":"Modifiers","text":"

Modifiers can appear before the operator, to change its behavior.

Modifier Description ! Not - negates the match : Case insensitive ? Treat empty match string as null [ Combine using AND on the same field ] Combine using OR on the same field (default)"},{"location":"reference/api_query_syntax/#detailed-examples","title":"Detailed examples","text":"Example Description cat Equals \"cat\" =cat Equals \"cat\" (same) !=cat Not equal to \"cat\" :=cat Equal to \"CAT\", \"cat\", \"CaT etc. !:cat Not equal to \"CAT\", \"cat\", \"CaT etc. =!cat Equal to \"!cat\" (! is after operator) ^cats/ Starts with \"cats/\" $_cat Ends with with \"_cat\" !:^cats/ Does not start with \"cats/\", \"CATs/\" etc. !$-cat Does not end with \"-cat\" ?= Is null !?= Is not null"},{"location":"reference/api_query_syntax/#time-range-example","title":"Time range example","text":"

For this case we need to combine multiple queries on the same created field using AND semantics (with the [) modifier:

?created=[>>2021-01-01T00:00:00Z&created=[<=2021-01-02T00:00:00Z\n

So this means:

  • created greater than 2021-01-01T00:00:00Z
  • AND
  • created less than or equal to 2021-01-02T00:00:00Z
"},{"location":"reference/blockchain_operation_errors/","title":"Blockchain Operation Errors","text":""},{"location":"reference/blockchain_operation_errors/#blockchain-error-messages","title":"Blockchain Error Messages","text":"

The receipt for a FireFly blockchain operation contains an extraInfo section that records additional information about the transaction. For example:

\"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

The errorMessage 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 errorMessage 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.

"},{"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":"

If FireFly is configured to connect to a Besu EVM client, and Besu has been configured with the revert-reason-enabled=true setting (note - the default value for Besu is false) error messages passed to FireFly from the blockchain client itself will be set correctly in the FireFly blockchain operation. For example:

  • \"errorMessage\":\"Not enough tokens\" for a revert error string from a smart contract

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:

  • \"errorMessage\":\"FF23053: Error return value for custom error: <revert hex string>
  • \"returnValue\":\"<revert hex string>\"

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.

If FireFly is configured to connect to Besu without revert-reason-enabled=true the error message will be set to:

  • \"errorMessage\":\"FF23054: Error return value unavailable\"
"},{"location":"reference/blockchain_operation_errors/#error-retrieval-details","title":"Error Retrieval Details","text":"

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 firefly-evmconnect blockchain connector.

"},{"location":"reference/blockchain_operation_errors/#format-of-a-firefly-evmconnect-error-message","title":"Format of a firefly-evmconnect Error Message","text":"

The following section describes the way that the firefly-evmconnect plugin uses the errorMessage 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.

The errorMessage field for a firefly-evmconnect transaction may contain one of the following:

  1. An error message from the FireFly blockchain connector
  2. For example \"FF23054: Error return value unavailable\"
  3. A decoded error string from the blockchain transaction
  4. For example Not enough tokens
  5. This could be an error string from a smart contract e.g. require(requestedTokens <= allowance, \"Not enough tokens\");
  6. An un-decoded byte string from the blockchain transaction
  7. For example 
    FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010\n
  8. This could be a custom error from a smart contract e.g. 
    error AllowanceTooSmall(uint256 requested, uint256 allowance);\n...\nrevert AllowanceTooSmall({ requested: 100, allowance: 20 });\n
  9. If an error reason cannot be decoded the returnValue of the extraInfo will be set to the raw byte string. For example: 
    \"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
"},{"location":"reference/blockchain_operation_errors/#retrieving-evm-blockchain-transaction-errors","title":"Retrieving EVM Blockchain Transaction Errors","text":"

The ability of a blockchain connector such as firefly-evmconnect 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 REVERT op code, with a REASON 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 --revert-reason-enabled 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 REVERT REASON. 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.

The firefly-evmconnect blockchain connector attempts to obtain the reason for a transaction revert and include it in the extraInfo field. It uses the following mechanisms, in this order:

  1. Checks if the blockchain transaction receipt contains the revert reason.
  2. If the revert reason is not in the receipt, and the connector.traceTXForRevertReason configuration option is set to true, calls debug_traceTransaction to obtain a full trace of the transaction and extract the revert reason. By default, connector.traceTXForRevertReason is set to false to avoid submitting high-resource requests to the EVM client.

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 Error(string) signature format and includes the decoded string in the errorMessage - If the reason is not a standard Error(String) error, sets the errorMessage to FF23053: Error return value for custom error: <raw hex string> and includes the raw byte string in the returnValue field.

"},{"location":"reference/blockchain_operation_status/","title":"Blockchain Operation Status","text":""},{"location":"reference/blockchain_operation_status/#blockchain-operations","title":"Blockchain Operations","text":"

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.

"},{"location":"reference/blockchain_operation_status/#blockchain-operation-status_1","title":"Blockchain Operation Status","text":"

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.

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:

To access detailed information about a blockchain operation FireFly 1.2 introduced a new query parameter, fetchStatus, to the /transaction/{txid}/operation/{opid} 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 detail field.

"},{"location":"reference/blockchain_operation_status/#blockchain-operation-example","title":"Blockchain Operation Example","text":"
{\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
"},{"location":"reference/blockchain_operation_status/#detail-status-structure","title":"Detail Status Structure","text":"

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:

  • history an ordered list of status changes that have taken place during processing of the transaction
  • 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.

The history 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 Received, moving to Tracking, and finally ending up as Confirmed. In order to move from Received to Tracking several actions were performed: AssignNonce, RetrieveGasPrice, and SubmitTransaction.

"},{"location":"reference/blockchain_operation_status/#history-example","title":"History Example","text":"
{\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

Because the history 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 assignNonce might only happen once when the transaction is first processed by the connector. The historySummary field ensures that a minimal set of information is kept about every single subStatus type and action that has been recorded.

"},{"location":"reference/blockchain_operation_status/#history-summary-example","title":"History Summary Example","text":"
{\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
"},{"location":"reference/blockchain_operation_status/#public-chain-operations","title":"Public Chain Operations","text":"

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 history for a public blockchain operation might include a large number of subStatus entries. Using the example sub-status values above, a blockchain operation might move from Tracking to Stale, back to Tracking, back to Stale and so on.

Below is an example of the history for a public blockchain operation.

"},{"location":"reference/blockchain_operation_status/#polygon-example","title":"Polygon Example","text":"
{\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
"},{"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 boolean <nil>"},{"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 int 25 dynamicPublicURLHeader Dynamic header that informs the backend the base public URL for the request, in order to build URL links in OpenAPI/SwaggerUI string <nil> maxFilterLimit The largest value of limit that an HTTP client can specify in a request int 1000 passthroughHeaders A list of HTTP request headers to pass through to dependency microservices []string [] requestMaxTimeout The maximum amount of time that an HTTP client can specify in a Request-Timeout header to keep a specific request open time.Duration 10m requestTimeout The maximum amount of time that a request is allowed to remain open time.Duration 120s"},{"location":"reference/config/#assetmanager","title":"asset.manager","text":"Key Description Type Default Value keyNormalization Mechanism to normalize keys before using them. Valid options are blockchain_plugin - use blockchain plugin (default) or none - do not attempt normalization (deprecated - use namespaces.predefined[].asset.manager.keyNormalization) string blockchain_plugin"},{"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 time.Duration 100ms pollTimeout How long to wait without any notifications of new messages before doing a page query time.Duration 30s readPageSize The size of each page of messages read from the database into memory when assembling batches int 100"},{"location":"reference/config/#batchretry","title":"batch.retry","text":"Key Description Type Default Value factor The retry backoff factor float32 2 initDelay The initial retry delay time.Duration 250ms maxDelay The maximum retry delay time.Duration 30s"},{"location":"reference/config/#blobreceiverretry","title":"blobreceiver.retry","text":"Key Description Type Default Value factor The retry backoff factor float32 2 initialDelay The initial retry delay time.Duration 250ms maxDelay The maximum retry delay time.Duration 1m"},{"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 int 200 batchTimeout The maximum amount of the the blob receiver worker will wait time.Duration 50ms count The number of blob receiver workers int 5"},{"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 string 2m payloadLimit The maximum payload size of a batch for broadcast messages BytesSize 800Kb size The maximum number of messages that can be packed into a batch int 200 timeout The timeout to wait for a batch to fill, before sending time.Duration 1s"},{"location":"reference/config/#cache","title":"cache","text":"Key Description Type Default Value enabled Enables caching, defaults to true boolean true"},{"location":"reference/config/#cacheaddressresolver","title":"cache.addressresolver","text":"Key Description Type Default Value limit Max number of cached items for address resolver int 1000 ttl Time to live of cached items for address resolver string 24h"},{"location":"reference/config/#cachebatch","title":"cache.batch","text":"Key Description Type Default Value limit Max number of cached items for batches int 100 ttl Time to live of cache items for batches string 5m"},{"location":"reference/config/#cacheblockchain","title":"cache.blockchain","text":"Key Description Type Default Value limit Max number of cached items for blockchain int 100 ttl Time to live of cached items for blockchain string 5m"},{"location":"reference/config/#cacheblockchainevent","title":"cache.blockchainevent","text":"Key Description Type Default Value limit Max number of cached blockchain events for transactions int 1000 ttl Time to live of cached blockchain events for transactions string 5m"},{"location":"reference/config/#cacheeventlistenertopic","title":"cache.eventlistenertopic","text":"Key Description Type Default Value limit Max number of cached items for blockchain listener topics int 100 ttl Time to live of cached items for blockchain listener topics string 5m"},{"location":"reference/config/#cachegroup","title":"cache.group","text":"Key Description Type Default Value limit Max number of cached items for groups int 50 ttl Time to live of cached items for groups string 1h"},{"location":"reference/config/#cacheidentity","title":"cache.identity","text":"Key Description Type Default Value limit Max number of cached identities for identity manager int 100 ttl Time to live of cached identities for identity manager string 1h"},{"location":"reference/config/#cachemessage","title":"cache.message","text":"Key Description Type Default Value size Max size of cached messages for data manager BytesSize 50Mb ttl Time to live of cached messages for data manager string 5m"},{"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 int 200 ttl Time to live of cached items for schema validations on blockchain methods string 5m"},{"location":"reference/config/#cacheoperations","title":"cache.operations","text":"Key Description Type Default Value limit Max number of cached items for operations int 1000 ttl Time to live of cached items for operations string 5m"},{"location":"reference/config/#cachetokenpool","title":"cache.tokenpool","text":"Key Description Type Default Value limit Max number of cached items for token pools int 100 ttl Time to live of cached items for token pool string 1h"},{"location":"reference/config/#cachetransaction","title":"cache.transaction","text":"Key Description Type Default Value size Max size of cached transactions BytesSize 1Mb ttl Time to live of cached transactions string 5m"},{"location":"reference/config/#cachevalidator","title":"cache.validator","text":"Key Description Type Default Value size Max size of cached validators for data manager BytesSize 1Mb ttl Time to live of cached validators for data manager string 1h"},{"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 boolean <nil>"},{"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 boolean true debug Whether debug is enabled for the CORS implementation boolean false enabled Whether CORS is enabled boolean true headers CORS setting to control the allowed headers []string [*] maxAge The maximum age a browser should rely on CORS checks time.Duration 600 methods CORS setting to control the allowed methods []string [GET POST PUT PATCH DELETE] origins CORS setting to control the allowed origins []string [*]"},{"location":"reference/config/#debug","title":"debug","text":"Key Description Type Default Value address The HTTP interface the go debugger binds to string localhost port An HTTP port on which to enable the go debugger int -1"},{"location":"reference/config/#downloadretry","title":"download.retry","text":"Key Description Type Default Value factor The retry backoff factor float32 2 initialDelay The initial retry delay time.Duration 100ms maxAttempts The maximum number attempts int 100 maxDelay The maximum retry delay time.Duration 1m"},{"location":"reference/config/#downloadworker","title":"download.worker","text":"Key Description Type Default Value count The number of download workers int 10 queueLength The length of the work queue in the channel to the workers - defaults to 2x the worker count int <nil>"},{"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 BytesSize 200 batchTimeout How long to wait for new events to arrive before performing aggregation on a page of events time.Duration 0ms firstEvent The first event the aggregator should process, if no previous offest is stored in the DB. Valid options are oldest or newest string oldest pollTimeout The time to wait without a notification of new events, before trying a select on the table time.Duration 30s rewindQueryLimit Safety limit on the maximum number of records to search when performing queries to search for rewinds int 1000 rewindQueueLength The size of the queue into the rewind dispatcher int 10 rewindTimeout The minimum time to wait for rewinds to accumulate before resolving them time.Duration 50ms"},{"location":"reference/config/#eventaggregatorretry","title":"event.aggregator.retry","text":"Key Description Type Default Value factor The retry backoff factor float32 2 initDelay The initial retry delay time.Duration 100ms maxDelay The maximum retry delay time.Duration 30s"},{"location":"reference/config/#eventdbevents","title":"event.dbevents","text":"Key Description Type Default Value bufferSize The size of the buffer of change events BytesSize 100"},{"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 time.Duration 0ms bufferLength The number of events + attachments an individual dispatcher should hold in memory ready for delivery to the subscription int 5 pollTimeout The time to wait without a notification of new events, before trying a select on the table time.Duration 30s"},{"location":"reference/config/#eventdispatcherretry","title":"event.dispatcher.retry","text":"Key Description Type Default Value factor The retry backoff factor float32 <nil> initDelay The initial retry delay time.Duration <nil> maxDelay The maximum retry delay time.Duration <nil>"},{"location":"reference/config/#eventtransports","title":"event.transports","text":"Key Description Type Default Value default The default event transport for new subscriptions string websockets enabled Which event interface plugins are enabled boolean [websockets webhooks]"},{"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 time.Duration 30s expectContinueTimeout See ExpectContinueTimeout in the Go docs time.Duration 1s headers Adds custom headers to HTTP requests map[string]string <nil> idleTimeout The max duration to hold a HTTP keepalive connection between calls time.Duration 475ms maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit int 0 maxIdleConns The max number of idle connections to hold pooled int 100 passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers boolean false requestTimeout The maximum amount of time that a request is allowed to remain open time.Duration 30s tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake time.Duration 10s"},{"location":"reference/config/#eventswebhooksauth","title":"events.webhooks.auth","text":"Key Description Type Default Value password Password string <nil> username Username string <nil>"},{"location":"reference/config/#eventswebhooksproxy","title":"events.webhooks.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to connect through string <nil>"},{"location":"reference/config/#eventswebhooksretry","title":"events.webhooks.retry","text":"Key Description Type Default Value count The maximum number of times to retry int 5 enabled Enables retries boolean false errorStatusCodeRegex The regex that the error response status code must match to trigger retry string <nil> initWaitTime The initial retry delay time.Duration 250ms maxWaitTime The maximum retry delay time.Duration 30s"},{"location":"reference/config/#eventswebhookstls","title":"events.webhooks.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"location":"reference/config/#eventswebsockets","title":"events.websockets","text":"Key Description Type Default Value readBufferSize WebSocket read buffer size BytesSize 16Kb writeBufferSize WebSocket write buffer size BytesSize 16Kb"},{"location":"reference/config/#histograms","title":"histograms","text":"Key Description Type Default Value maxChartRows The maximum rows to fetch for each histogram bucket int 100"},{"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 string 127.0.0.1 port The port on which the HTTP API should listen int 5000 publicURL The fully qualified public URL for the API. This is used for building URLs in HTTP responses and in OpenAPI Spec generation URL string <nil> readTimeout The maximum time to wait when reading from an HTTP connection time.Duration 15s shutdownTimeout The maximum amount of time to wait for any open HTTP requests to finish before shutting down the HTTP server time.Duration 10s writeTimeout The maximum time to wait when writing to an HTTP connection time.Duration 15s"},{"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 string <nil>"},{"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. string <nil>"},{"location":"reference/config/#httptls","title":"http.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"location":"reference/config/#log","title":"log","text":"Key Description Type Default Value compress Determines if the rotated log files should be compressed using gzip boolean <nil> filename Filename is the file to write logs to. Backup log files will be retained in the same directory string <nil> filesize MaxSize is the maximum size the log file before it gets rotated BytesSize 100m forceColor Force color to be enabled, even when a non-TTY output is detected boolean <nil> 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. boolean false level The log level - error, warn, info, debug, trace string info maxAge The maximum time to retain old log files based on the timestamp encoded in their filename time.Duration 24h maxBackups Maximum number of old log files to retain int 2 noColor Force color to be disabled, event when TTY output is detected boolean <nil> timeFormat Custom time format for logs Time format string 2006-01-02T15:04:05.000Z07:00 utc Use UTC timestamps for logs boolean false"},{"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. boolean false"},{"location":"reference/config/#logjsonfields","title":"log.json.fields","text":"Key Description Type Default Value file configures the JSON key containing the calling file string file func Configures the JSON key containing the calling function string func level Configures the JSON key containing the log level string level message Configures the JSON key containing the log message string message timestamp Configures the JSON key containing the timestamp of the log string @timestamp"},{"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 int 200 batchTimeout How long to wait for more messages to arrive before flushing the batch time.Duration 10ms count The number of message writer workers int 5"},{"location":"reference/config/#metrics","title":"metrics","text":"Key Description Type Default Value address The IP address on which the metrics HTTP API should listen int 127.0.0.1 enabled Enables the metrics API boolean true path The path from which to serve the Prometheus metrics string /metrics port The port on which the metrics HTTP API should listen int 6000 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 string <nil> readTimeout The maximum time to wait when reading from an HTTP connection time.Duration 15s shutdownTimeout The maximum amount of time to wait for any open HTTP requests to finish before shutting down the HTTP server time.Duration 10s writeTimeout The maximum time to wait when writing to an HTTP connection time.Duration 15s"},{"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 string <nil>"},{"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. string <nil>"},{"location":"reference/config/#metricstls","title":"metrics.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"location":"reference/config/#namespaces","title":"namespaces","text":"Key Description Type Default Value default The default namespace - must be in the predefined list string default predefined A list of namespaces to ensure exists, without requiring a broadcast from the network List string <nil>"},{"location":"reference/config/#namespacespredefined","title":"namespaces.predefined[]","text":"Key Description Type Default Value defaultKey A default signing key for blockchain transactions within this namespace string <nil> description A description for the namespace string <nil> name The name of the namespace (must be unique) string <nil> plugins The list of plugins for this namespace string <nil>"},{"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 blockchain_plugin - use blockchain plugin (default) or none - do not attempt normalization string <nil>"},{"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) boolean <nil> networknamespace The shared namespace name to be sent in multiparty messages, if it differs from the local namespace name string <nil>"},{"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 oldest or newest string <nil> location A blockchain-specific contract location. For example, an Ethereum contract address, or a Fabric chaincode name and channel string <nil> options Blockchain-specific contract options string <nil>"},{"location":"reference/config/#namespacespredefinedmultipartynode","title":"namespaces.predefined[].multiparty.node","text":"Key Description Type Default Value description A description for the node in this namespace string <nil> name The node name for this namespace string <nil>"},{"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 string <nil> key The signing key allocated to the root organization within this namespace string <nil> name A short name for the local root organization within this namespace string <nil>"},{"location":"reference/config/#namespacespredefinedtlsconfigs","title":"namespaces.predefined[].tlsConfigs[]","text":"Key Description Type Default Value name Name of the TLS Config string <nil>"},{"location":"reference/config/#namespacespredefinedtlsconfigstls","title":"namespaces.predefined[].tlsConfigs[].tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"location":"reference/config/#namespacesretry","title":"namespaces.retry","text":"Key Description Type Default Value factor The retry backoff factor float32 2 initDelay The initial retry delay time.Duration 5s maxDelay The maximum retry delay time.Duration 1m"},{"location":"reference/config/#node","title":"node","text":"Key Description Type Default Value description The description of this FireFly node string <nil> name The name of this FireFly node string <nil>"},{"location":"reference/config/#opupdateretry","title":"opupdate.retry","text":"Key Description Type Default Value factor The retry backoff factor float32 2 initialDelay The initial retry delay time.Duration 250ms maxDelay The maximum retry delay time.Duration 1m"},{"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 int 200 batchTimeout How long to wait for more messages to arrive before flushing the batch time.Duration 50ms count The number of operation update works int 5 queueLength The size of the queue for the Operation Update worker int 50"},{"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 string 5"},{"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) string <nil> key The signing key allocated to the organization (deprecated - should be set on each multi-party namespace instead) string <nil> name The name of the organization to which this FireFly node belongs (deprecated - should be set on each multi-party namespace instead) string <nil>"},{"location":"reference/config/#plugins","title":"plugins","text":"Key Description Type Default Value auth Authorization plugin configuration map[string]string <nil> blockchain The list of configured Blockchain plugins string <nil> database The list of configured Database plugins string <nil> dataexchange The array of configured Data Exchange plugins string <nil> identity The list of available Identity plugins string <nil> sharedstorage The list of configured Shared Storage plugins string <nil> tokens The token plugin configurations string <nil>"},{"location":"reference/config/#pluginsauth","title":"plugins.auth[]","text":"Key Description Type Default Value name The name of the auth plugin to use string <nil> type The type of the auth plugin to use string <nil>"},{"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. string <nil>"},{"location":"reference/config/#pluginsblockchain","title":"plugins.blockchain[]","text":"Key Description Type Default Value name The name of the configured Blockchain plugin string <nil> type The type of the configured Blockchain Connector plugin string <nil>"},{"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 boolean <nil> bodyTemplate The body go template string to use when making HTTP requests. The template input contains '.Key' and '.Intent' string variables. Go Template string <nil> connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted time.Duration 30s expectContinueTimeout See ExpectContinueTimeout in the Go docs time.Duration 1s headers Adds custom headers to HTTP requests string <nil> idleTimeout The max duration to hold a HTTP keepalive connection between calls time.Duration 475ms maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit int 0 maxIdleConns The max number of idle connections to hold pooled int 100 method The HTTP method to use when making requests to the Address Resolver string GET passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers boolean false requestTimeout The maximum amount of time that a request is allowed to remain open time.Duration 30s responseField The name of a JSON field that is provided in the response, that contains the ethereum address (default address) string address retainOriginal When true the original pre-resolved string is retained after the lookup, and passed down to Ethconnect as the from address boolean <nil> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake time.Duration 10s url The URL of the Address Resolver string <nil> urlTemplate The URL Go template string to use when calling the Address Resolver. The template input contains '.Key' and '.Intent' string variables. Go Template string <nil>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolverauth","title":"plugins.blockchain[].ethereum.addressResolver.auth","text":"Key Description Type Default Value password Password string <nil> username Username string <nil>"},{"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 string <nil>"},{"location":"reference/config/#pluginsblockchainethereumaddressresolverretry","title":"plugins.blockchain[].ethereum.addressResolver.retry","text":"Key Description Type Default Value count The maximum number of times to retry int 5 enabled Enables retries boolean false errorStatusCodeRegex The regex that the error response status code must match to trigger retry string <nil> initWaitTime The initial retry delay time.Duration 250ms maxWaitTime The maximum retry delay time.Duration 30s"},{"location":"reference/config/#pluginsblockchainethereumaddressresolvertls","title":"plugins.blockchain[].ethereum.addressResolver.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"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 int 50 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 time.Duration 500 connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted time.Duration 30s expectContinueTimeout See ExpectContinueTimeout in the Go docs time.Duration 1s 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 string 0 headers Adds custom headers to HTTP requests map[string]string <nil> idleTimeout The max duration to hold a HTTP keepalive connection between calls time.Duration 475ms instance The Ethereum address of the FireFly BatchPin smart contract that has been deployed to the blockchain Address string <nil> maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit int 0 maxIdleConns The max number of idle connections to hold pooled int 100 passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers boolean false prefixLong The prefix that will be used for Ethconnect specific HTTP headers when FireFly makes requests to Ethconnect string firefly prefixShort The prefix that will be used for Ethconnect specific query parameters when FireFly makes requests to Ethconnect string fly requestTimeout The maximum amount of time that a request is allowed to remain open time.Duration 30s tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake time.Duration 10s topic The websocket listen topic that the node should register on, which is important if there are multiple nodes using a single ethconnect string <nil> url The URL of the Ethconnect instance URL string <nil>"},{"location":"reference/config/#pluginsblockchainethereumethconnectauth","title":"plugins.blockchain[].ethereum.ethconnect.auth","text":"Key Description Type Default Value password Password string <nil> username Username string <nil>"},{"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 boolean <nil> factor Set the factor by which the delay increases when retrying float32 2 initialDelay Delay between restarts in the case where we retry to restart the ethereum plugin time.Duration 5s maxDelay Max delay between restarts in the case where we retry to restart the ethereum plugin time.Duration 1m"},{"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 string <nil>"},{"location":"reference/config/#pluginsblockchainethereumethconnectretry","title":"plugins.blockchain[].ethereum.ethconnect.retry","text":"Key Description Type Default Value count The maximum number of times to retry int 5 enabled Enables retries boolean false errorStatusCodeRegex The regex that the error response status code must match to trigger retry string <nil> initWaitTime The initial retry delay time.Duration 250ms maxWaitTime The maximum retry delay time.Duration 30s"},{"location":"reference/config/#pluginsblockchainethereumethconnecttls","title":"plugins.blockchain[].ethereum.ethconnect.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"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) time.Duration 45s heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection time.Duration 30s initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing int 5 path The WebSocket sever URL to which FireFly should connect WebSocket URL string <nil> readBufferSize The size in bytes of the read buffer for the WebSocket connection BytesSize 16Kb url URL to use for WebSocket - overrides url one level up (in the HTTP config) string <nil> writeBufferSize The size in bytes of the write buffer for the WebSocket connection BytesSize 16Kb"},{"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 time.Duration 30s expectContinueTimeout See ExpectContinueTimeout in the Go docs time.Duration 1s headers Adds custom headers to HTTP requests map[string]string <nil> idleTimeout The max duration to hold a HTTP keepalive connection between calls time.Duration 475ms maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit int 0 maxIdleConns The max number of idle connections to hold pooled int 100 passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers boolean false requestTimeout The maximum amount of time that a request is allowed to remain open time.Duration 30s tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake time.Duration 10s url The URL of the FireFly Transaction Manager runtime, if enabled string <nil>"},{"location":"reference/config/#pluginsblockchainethereumfftmauth","title":"plugins.blockchain[].ethereum.fftm.auth","text":"Key Description Type Default Value password Password string <nil> username Username string <nil>"},{"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 string <nil>"},{"location":"reference/config/#pluginsblockchainethereumfftmretry","title":"plugins.blockchain[].ethereum.fftm.retry","text":"Key Description Type Default Value count The maximum number of times to retry int 5 enabled Enables retries boolean false errorStatusCodeRegex The regex that the error response status code must match to trigger retry string <nil> initWaitTime The initial retry delay time.Duration 250ms maxWaitTime The maximum retry delay time.Duration 30s"},{"location":"reference/config/#pluginsblockchainethereumfftmtls","title":"plugins.blockchain[].ethereum.fftm.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"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 int 50 batchTimeout The maximum amount of time to wait for a batch to complete time.Duration 500 chaincode The name of the Fabric chaincode that FireFly will use for BatchPin transactions (deprecated - use fireflyContract[].chaincode) string <nil> channel The Fabric channel that FireFly will use for BatchPin transactions string <nil> connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted time.Duration 30s expectContinueTimeout See ExpectContinueTimeout in the Go docs time.Duration 1s headers Adds custom headers to HTTP requests map[string]string <nil> idleTimeout The max duration to hold a HTTP keepalive connection between calls time.Duration 475ms maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit int 0 maxIdleConns The max number of idle connections to hold pooled int 100 passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers boolean false prefixLong The prefix that will be used for Fabconnect specific HTTP headers when FireFly makes requests to Fabconnect string firefly prefixShort The prefix that will be used for Fabconnect specific query parameters when FireFly makes requests to Fabconnect string fly requestTimeout The maximum amount of time that a request is allowed to remain open time.Duration 30s signer The Fabric signing key to use when submitting transactions to Fabconnect string <nil> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake time.Duration 10s topic The websocket listen topic that the node should register on, which is important if there are multiple nodes using a single Fabconnect string <nil> url The URL of the Fabconnect instance URL string <nil>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectauth","title":"plugins.blockchain[].fabric.fabconnect.auth","text":"Key Description Type Default Value password Password string <nil> username Username string <nil>"},{"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 boolean <nil> factor Set the factor by which the delay increases when retrying float32 2 initialDelay Delay between restarts in the case where we retry to restart the fabric plugin time.Duration 5s maxDelay Max delay between restarts in the case where we retry to restart the fabric plugin time.Duration 1m"},{"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 string <nil>"},{"location":"reference/config/#pluginsblockchainfabricfabconnectretry","title":"plugins.blockchain[].fabric.fabconnect.retry","text":"Key Description Type Default Value count The maximum number of times to retry int 5 enabled Enables retries boolean false errorStatusCodeRegex The regex that the error response status code must match to trigger retry string <nil> initWaitTime The initial retry delay time.Duration 250ms maxWaitTime The maximum retry delay time.Duration 30s"},{"location":"reference/config/#pluginsblockchainfabricfabconnecttls","title":"plugins.blockchain[].fabric.fabconnect.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"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) time.Duration 45s heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection time.Duration 30s initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing int 5 path The WebSocket sever URL to which FireFly should connect WebSocket URL string <nil> readBufferSize The size in bytes of the read buffer for the WebSocket connection BytesSize 16Kb url URL to use for WebSocket - overrides url one level up (in the HTTP config) string <nil> writeBufferSize The size in bytes of the write buffer for the WebSocket connection BytesSize 16Kb"},{"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 boolean <nil> bodyTemplate The body go template string to use when making HTTP requests Go Template string <nil> connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted time.Duration 30s expectContinueTimeout See ExpectContinueTimeout in the Go docs time.Duration 1s headers Adds custom headers to HTTP requests map[string]string <nil> idleTimeout The max duration to hold a HTTP keepalive connection between calls time.Duration 475ms maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit int 0 maxIdleConns The max number of idle connections to hold pooled int 100 method The HTTP method to use when making requests to the Address Resolver string GET passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers boolean false requestTimeout The maximum amount of time that a request is allowed to remain open time.Duration 30s responseField The name of a JSON field that is provided in the response, that contains the tezos address (default address) string address retainOriginal When true the original pre-resolved string is retained after the lookup, and passed down to Tezosconnect as the from address boolean <nil> tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake time.Duration 10s url The URL of the Address Resolver string <nil> urlTemplate The URL Go template string to use when calling the Address Resolver. The template input contains '.Key' and '.Intent' string variables. Go Template string <nil>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolverauth","title":"plugins.blockchain[].tezos.addressResolver.auth","text":"Key Description Type Default Value password Password string <nil> username Username string <nil>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolverproxy","title":"plugins.blockchain[].tezos.addressResolver.proxy","text":"Key Description Type Default Value url Optional HTTP proxy server to connect through string <nil>"},{"location":"reference/config/#pluginsblockchaintezosaddressresolverretry","title":"plugins.blockchain[].tezos.addressResolver.retry","text":"Key Description Type Default Value count The maximum number of times to retry int 5 enabled Enables retries boolean false errorStatusCodeRegex The regex that the error response status code must match to trigger retry string <nil> initWaitTime The initial retry delay time.Duration 250ms maxWaitTime The maximum retry delay time.Duration 30s"},{"location":"reference/config/#pluginsblockchaintezosaddressresolvertls","title":"plugins.blockchain[].tezos.addressResolver.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"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 int 50 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 time.Duration 500 connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted time.Duration 30s expectContinueTimeout See ExpectContinueTimeout in the Go docs time.Duration 1s headers Adds custom headers to HTTP requests map[string]string <nil> idleTimeout The max duration to hold a HTTP keepalive connection between calls time.Duration 475ms maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit int 0 maxIdleConns The max number of idle connections to hold pooled int 100 passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers boolean false prefixLong The prefix that will be used for Tezosconnect specific HTTP headers when FireFly makes requests to Tezosconnect string firefly prefixShort The prefix that will be used for Tezosconnect specific query parameters when FireFly makes requests to Tezosconnect string fly requestTimeout The maximum amount of time that a request is allowed to remain open time.Duration 30s tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake time.Duration 10s topic The websocket listen topic that the node should register on, which is important if there are multiple nodes using a single tezosconnect string <nil> url The URL of the Tezosconnect instance URL string <nil>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectauth","title":"plugins.blockchain[].tezos.tezosconnect.auth","text":"Key Description Type Default Value password Password string <nil> username Username string <nil>"},{"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 boolean <nil> factor Set the factor by which the delay increases when retrying float32 2 initialDelay Delay between restarts in the case where we retry to restart the tezos plugin time.Duration 5s maxDelay Max delay between restarts in the case where we retry to restart the tezos plugin time.Duration 1m"},{"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 string <nil>"},{"location":"reference/config/#pluginsblockchaintezostezosconnectretry","title":"plugins.blockchain[].tezos.tezosconnect.retry","text":"Key Description Type Default Value count The maximum number of times to retry int 5 enabled Enables retries boolean false errorStatusCodeRegex The regex that the error response status code must match to trigger retry string <nil> initWaitTime The initial retry delay time.Duration 250ms maxWaitTime The maximum retry delay time.Duration 30s"},{"location":"reference/config/#pluginsblockchaintezostezosconnecttls","title":"plugins.blockchain[].tezos.tezosconnect.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"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) time.Duration 45s heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection time.Duration 30s initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing int 5 path The WebSocket sever URL to which FireFly should connect WebSocket URL string <nil> readBufferSize The size in bytes of the read buffer for the WebSocket connection BytesSize 16Kb url URL to use for WebSocket - overrides url one level up (in the HTTP config) string <nil> writeBufferSize The size in bytes of the write buffer for the WebSocket connection BytesSize 16Kb"},{"location":"reference/config/#pluginsdatabase","title":"plugins.database[]","text":"Key Description Type Default Value name The name of the Database plugin string <nil> type The type of the configured Database plugin string <nil>"},{"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 time.Duration 1m maxConnLifetime The maximum amount of time to keep a database connection open time.Duration <nil> maxConns Maximum connections to the database int 50 maxIdleConns The maximum number of idle connections to the database int <nil> url The PostgreSQL connection string for the database string <nil>"},{"location":"reference/config/#pluginsdatabasepostgresmigrations","title":"plugins.database[].postgres.migrations","text":"Key Description Type Default Value auto Enables automatic database migrations boolean false directory The directory containing the numerically ordered migration DDL files to apply to the database string ./db/migrations/postgres"},{"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 time.Duration 1m maxConnLifetime The maximum amount of time to keep a database connection open time.Duration <nil> maxConns Maximum connections to the database int 1 maxIdleConns The maximum number of idle connections to the database int <nil> url The SQLite connection string for the database string <nil>"},{"location":"reference/config/#pluginsdatabasesqlite3migrations","title":"plugins.database[].sqlite3.migrations","text":"Key Description Type Default Value auto Enables automatic database migrations boolean false directory The directory containing the numerically ordered migration DDL files to apply to the database string ./db/migrations/sqlite"},{"location":"reference/config/#pluginsdataexchange","title":"plugins.dataexchange[]","text":"Key Description Type Default Value name The name of the configured Data Exchange plugin string <nil> type The Data Exchange plugin to use string <nil>"},{"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 time.Duration 30s expectContinueTimeout See ExpectContinueTimeout in the Go docs time.Duration 1s headers Adds custom headers to HTTP requests map[string]string <nil> idleTimeout The max duration to hold a HTTP keepalive connection between calls time.Duration 475ms initEnabled Instructs FireFly to always post all current nodes to the /init API before connecting or reconnecting to the connector boolean false manifestEnabled Determines whether to require+validate a manifest from other DX instances in the network. Must be supported by the connector string false maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit int 0 maxIdleConns The max number of idle connections to hold pooled int 100 passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers boolean false requestTimeout The maximum amount of time that a request is allowed to remain open time.Duration 30s tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake time.Duration 10s url The URL of the Data Exchange instance URL string <nil>"},{"location":"reference/config/#pluginsdataexchangeffdxauth","title":"plugins.dataexchange[].ffdx.auth","text":"Key Description Type Default Value password Password string <nil> username Username string <nil>"},{"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 boolean false factor Set the factor by which the delay increases when retrying float32 2 initialDelay Delay between restarts in the case where we retry to restart the data exchange plugin time.Duration 5s maxDelay Max delay between restarts in the case where we retry to restart the data exchange plugin time.Duration 1m"},{"location":"reference/config/#pluginsdataexchangeffdxeventretry","title":"plugins.dataexchange[].ffdx.eventRetry","text":"Key Description Type Default Value factor The retry backoff factor, for event processing float32 2 initialDelay The initial retry delay, for event processing time.Duration 50ms maxDelay The maximum retry delay, for event processing time.Duration 30s"},{"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 string <nil>"},{"location":"reference/config/#pluginsdataexchangeffdxretry","title":"plugins.dataexchange[].ffdx.retry","text":"Key Description Type Default Value count The maximum number of times to retry int 5 enabled Enables retries boolean false errorStatusCodeRegex The regex that the error response status code must match to trigger retry string <nil> initWaitTime The initial retry delay time.Duration 250ms maxWaitTime The maximum retry delay time.Duration 30s"},{"location":"reference/config/#pluginsdataexchangeffdxtls","title":"plugins.dataexchange[].ffdx.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"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) time.Duration 45s heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection time.Duration 30s initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing int 5 path The WebSocket sever URL to which FireFly should connect WebSocket URL string <nil> readBufferSize The size in bytes of the read buffer for the WebSocket connection BytesSize 16Kb url URL to use for WebSocket - overrides url one level up (in the HTTP config) string <nil> writeBufferSize The size in bytes of the write buffer for the WebSocket connection BytesSize 16Kb"},{"location":"reference/config/#pluginsidentity","title":"plugins.identity[]","text":"Key Description Type Default Value name The name of a configured Identity plugin string <nil> type The type of a configured Identity plugin string <nil>"},{"location":"reference/config/#pluginssharedstorage","title":"plugins.sharedstorage[]","text":"Key Description Type Default Value name The name of the Shared Storage plugin to use string <nil> type The Shared Storage plugin to use string <nil>"},{"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 time.Duration 30s expectContinueTimeout See ExpectContinueTimeout in the Go docs time.Duration 1s headers Adds custom headers to HTTP requests map[string]string <nil> idleTimeout The max duration to hold a HTTP keepalive connection between calls time.Duration 475ms maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit int 0 maxIdleConns The max number of idle connections to hold pooled int 100 passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers boolean false requestTimeout The maximum amount of time that a request is allowed to remain open time.Duration 30s tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake time.Duration 10s url The URL for the IPFS API URL string <nil>"},{"location":"reference/config/#pluginssharedstorageipfsapiauth","title":"plugins.sharedstorage[].ipfs.api.auth","text":"Key Description Type Default Value password Password string <nil> username Username string <nil>"},{"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 string <nil>"},{"location":"reference/config/#pluginssharedstorageipfsapiretry","title":"plugins.sharedstorage[].ipfs.api.retry","text":"Key Description Type Default Value count The maximum number of times to retry int 5 enabled Enables retries boolean false errorStatusCodeRegex The regex that the error response status code must match to trigger retry string <nil> initWaitTime The initial retry delay time.Duration 250ms maxWaitTime The maximum retry delay time.Duration 30s"},{"location":"reference/config/#pluginssharedstorageipfsapitls","title":"plugins.sharedstorage[].ipfs.api.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"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 time.Duration 30s expectContinueTimeout See ExpectContinueTimeout in the Go docs time.Duration 1s headers Adds custom headers to HTTP requests map[string]string <nil> idleTimeout The max duration to hold a HTTP keepalive connection between calls time.Duration 475ms maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit int 0 maxIdleConns The max number of idle connections to hold pooled int 100 passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers boolean false requestTimeout The maximum amount of time that a request is allowed to remain open time.Duration 30s tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake time.Duration 10s url The URL for the IPFS Gateway URL string <nil>"},{"location":"reference/config/#pluginssharedstorageipfsgatewayauth","title":"plugins.sharedstorage[].ipfs.gateway.auth","text":"Key Description Type Default Value password Password string <nil> username Username string <nil>"},{"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 string <nil>"},{"location":"reference/config/#pluginssharedstorageipfsgatewayretry","title":"plugins.sharedstorage[].ipfs.gateway.retry","text":"Key Description Type Default Value count The maximum number of times to retry int 5 enabled Enables retries boolean false errorStatusCodeRegex The regex that the error response status code must match to trigger retry string <nil> initWaitTime The initial retry delay time.Duration 250ms maxWaitTime The maximum retry delay time.Duration 30s"},{"location":"reference/config/#pluginssharedstorageipfsgatewaytls","title":"plugins.sharedstorage[].ipfs.gateway.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"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 string <nil> name A name to identify this token plugin string <nil> type The type of the token plugin to use string <nil>"},{"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 time.Duration 30s expectContinueTimeout See ExpectContinueTimeout in the Go docs time.Duration 1s headers Adds custom headers to HTTP requests map[string]string <nil> idleTimeout The max duration to hold a HTTP keepalive connection between calls time.Duration 475ms maxConnsPerHost The max number of connections, per unique hostname. Zero means no limit int 0 maxIdleConns The max number of idle connections to hold pooled int 100 passthroughHeadersEnabled Enable passing through the set of allowed HTTP request headers boolean false requestTimeout The maximum amount of time that a request is allowed to remain open time.Duration 30s tlsHandshakeTimeout The maximum amount of time to wait for a successful TLS handshake time.Duration 10s url The URL of the token connector URL string <nil>"},{"location":"reference/config/#pluginstokensfftokensauth","title":"plugins.tokens[].fftokens.auth","text":"Key Description Type Default Value password Password string <nil> username Username string <nil>"},{"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 boolean false factor Set the factor by which the delay increases when retrying float32 2 initialDelay Delay between restarts in the case where we retry to restart the token plugin time.Duration 5s maxDelay Max delay between restarts in the case where we retry to restart the token plugin time.Duration 1m"},{"location":"reference/config/#pluginstokensfftokenseventretry","title":"plugins.tokens[].fftokens.eventRetry","text":"Key Description Type Default Value factor The retry backoff factor, for event processing float32 2 initialDelay The initial retry delay, for event processing time.Duration 50ms maxDelay The maximum retry delay, for event processing time.Duration 30s"},{"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 string <nil>"},{"location":"reference/config/#pluginstokensfftokensretry","title":"plugins.tokens[].fftokens.retry","text":"Key Description Type Default Value count The maximum number of times to retry int 5 enabled Enables retries boolean false errorStatusCodeRegex The regex that the error response status code must match to trigger retry string <nil> initWaitTime The initial retry delay time.Duration 250ms maxWaitTime The maximum retry delay time.Duration 30s"},{"location":"reference/config/#pluginstokensfftokenstls","title":"plugins.tokens[].fftokens.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"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) time.Duration 45s heartbeatInterval The amount of time to wait between heartbeat signals on the WebSocket connection time.Duration 30s initialConnectAttempts The number of attempts FireFly will make to connect to the WebSocket when starting up, before failing int 5 path The WebSocket sever URL to which FireFly should connect WebSocket URL string <nil> readBufferSize The size in bytes of the read buffer for the WebSocket connection BytesSize 16Kb url URL to use for WebSocket - overrides url one level up (in the HTTP config) string <nil> writeBufferSize The size in bytes of the write buffer for the WebSocket connection BytesSize 16Kb"},{"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 time.Duration 2m payloadLimit The maximum payload size of a private message Data Exchange payload BytesSize 800Kb size The maximum number of messages in a batch for private messages int 200 timeout The timeout to wait for a batch to fill, before sending time.Duration 1s"},{"location":"reference/config/#privatemessagingretry","title":"privatemessaging.retry","text":"Key Description Type Default Value factor The retry backoff factor float32 2 initDelay The initial retry delay time.Duration 100ms maxDelay The maximum retry delay time.Duration 30s"},{"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 string 127.0.0.1 enabled Enables the admin HTTP API boolean false port The port on which the admin HTTP API should listen int 5001 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 string <nil> readTimeout The maximum time to wait when reading from an HTTP connection time.Duration 15s shutdownTimeout The maximum amount of time to wait for any open HTTP requests to finish before shutting down the HTTP server time.Duration 10s writeTimeout The maximum time to wait when writing to an HTTP connection time.Duration 15s"},{"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 string <nil>"},{"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. string <nil>"},{"location":"reference/config/#spitls","title":"spi.tls","text":"Key Description Type Default Value caFile The path to the CA file for TLS on this API string <nil> certFile The path to the certificate file for TLS on this API string <nil> clientAuth Enables or disables client auth for TLS on this API string <nil> enabled Enables or disables TLS on this API boolean false insecureSkipHostVerify When to true in unit test development environments to disable TLS verification. Use with extreme caution boolean <nil> keyFile The path to the private key file for TLS on this API string <nil> 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) map[string]string <nil>"},{"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 time.Duration 1m eventQueueLength Server-side queue length for events waiting for delivery over an admin change event listener websocket int 250 readBufferSize The size in bytes of the read buffer for the WebSocket connection BytesSize 16Kb writeBufferSize The size in bytes of the write buffer for the WebSocket connection BytesSize 16Kb"},{"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) int 500"},{"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 int 50 batchTimeout Default batch timeout int 50ms"},{"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 int 1000"},{"location":"reference/config/#subscriptionretry","title":"subscription.retry","text":"Key Description Type Default Value factor The retry backoff factor float32 2 initDelay The initial retry delay time.Duration 250ms maxDelay The maximum retry delay time.Duration 30s"},{"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 int 100 batchTimeout How long to wait for more transactions to arrive before flushing the batch time.Duration 10ms count The number of message writer workers int 5"},{"location":"reference/config/#ui","title":"ui","text":"Key Description Type Default Value enabled Enables the web user interface boolean true path The file system path which contains the static HTML, CSS, and JavaScript files for the user interface string <nil>"},{"location":"reference/events/","title":"Event Bus","text":""},{"location":"reference/events/#hyperledger-firefly-event-bus","title":"Hyperledger FireFly Event Bus","text":"

The FireFly event bus provides your application with a single stream of events from all of the back-end services that plug into FireFly.

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.

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 namespace, or can use server-side filtering to only receive a sub-set of events.

The event bus reliably keeps track of which events have been delivered to which applications, via an offset into the main event stream that is updated each time an application acknowledges receipt of events over its subscription.

"},{"location":"reference/events/#event-driven-application-architecture","title":"Event-Driven Application Architecture","text":"

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.

This requires an event-driven programming model.

You will find an event-driven model at the core of every blockchain Smart Contract technology.

This event-driven approach is unavoidable regardless of how much of your business data & logic can be directly stored/processed on-chain, vs. off-chain.

So Hyperledger FireFly aims to provide you with the tools to easily manage this model throughout your decentralized application stack.

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.

FireFly comes with a built in event processor for Token transfers & approvals, that implements this pattern to maintain balances, and transaction history in a rich query off-chain data cache.

"},{"location":"reference/events/#decentralized-event-processing","title":"Decentralized Event Processing","text":"

In a decentralized system, you need to consider that each organization runs its own applications, and has its own private database.

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.

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

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

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.

Let's look at a couple of examples.

"},{"location":"reference/events/#example-1-a-fungible-token-balance-transfer","title":"Example 1: A fungible token balance transfer","text":"

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.

This means the transaction must be backed by a blockchain verifiable by all participants on the network that could hold balances of that token.

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.

"},{"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":"

Here it is likely you want to restrict visibility of the data to just the parties directly involved in the business process.

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.

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.

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.

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.

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.

"},{"location":"reference/events/#privacy-groups-and-late-join","title":"Privacy groups and late join","text":"

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.

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.

Using a single Ethereum permissioned side-chain for example.

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.

Using Hyperledger Fabric channels for example.

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.

These private data exchanges can also be coordinated with most sophisticated on-chain transactions, such as token transfers.

"},{"location":"reference/events/#event-types","title":"Event Types","text":"

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.

All events in FireFly share a common base structure, regardless of their type. They are then linked (via a reference) to an object that contains detailed information.

The categories of event your application can receive are as follows:

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.

"},{"location":"reference/events/#blockchain-events","title":"Blockchain events","text":"

FireFly allows your application to subscribe to any event from a blockchain smart contract.

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

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

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

Check out the Custom Contracts Tutorial for a walk-through of how to set up listeners for the events from your smart contracts.

FireFly automatically establishes listeners for some blockchain events:

  • Events from the FireFly BatchPin contract that is used to pin identities, off-chain data broadcast and private messaging to the blockchain.

  • Events from Token contracts, for which a Token Pool has been configured. These events are detected indirectly via the token connector.

"},{"location":"reference/events/#token-events","title":"Token events","text":"

FireFly provides a Wallet API, that is pluggable to multiple token implementations without needing to change your app.

The pluggable API/Event interface allows all kinds of technical implementations of tokens to be fitted into a common framework.

The following wallet operations are supported. These are universal to all token implementations - NFTs and fungible tokens alike:

  • Mint
  • Burn
  • Transfer
  • Approve

FireFly processes, indexes and stores the events associated with these actions, for any Token Pool that has been configured on the FireFly node.

See Token Transfer and Token Approval for more information on the individual operations.

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.

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.

"},{"location":"reference/events/#message-events-on-chain-off-chain-coordinated","title":"Message events: on-chain / off-chain coordinated","text":"

Event aggregation between data arriving off-chain, and the associated ordered proof/transaction events being confirmed on-chain, is a complex orchestration task.

The universal order and additional transaction logic on-chain must be the source of truth for when and how an event is processed.

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.

They might arrive in any order, and no further events can be processed on that business transaction until the data is available.

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.

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 topic have been processed successfully by your application.

Your application just needs to:

  1. Choose a suitable topic for your messages that determines the ordered stream it is part of. Such as a business transaction identifier.
  2. Make sure the application does not acknowledge a message, until it has finished processing it.

See Message for more information

"},{"location":"reference/events/#transaction-submission-events","title":"Transaction submission events","text":"

These events are emitted each time a new transaction is initiated via the Firefly API.

These events are only emitted on the local FireFly node that initiates an activity.

For more information about FireFly Transactions, and how they relate to blockchain transactions, see Transaction.

"},{"location":"reference/firefly_interface_format/","title":"FireFly Interface Format","text":"

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.

"},{"location":"reference/firefly_interface_format/#overview","title":"Overview","text":"

There are four required fields when broadcasting a contract interface in FireFly: a name, a version, a list of methods, and a list of events. A namespace field will also be filled in automatically based on the URL path parameter. Here is an example of the structure of the required fields:

{\n  \"name\": \"example\",\n  \"version\": \"v1.0.0\",\n  \"methods\": [],\n  \"events\": []\n}\n

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.

"},{"location":"reference/firefly_interface_format/#method","title":"Method","text":"

Let's look at a what goes inside the methods array now. It is also a JSON object that has a name, a list of params which are the arguments the function will take and a list of returns which are the return values of the function. It also has an optional description which can be helpful in OpenAPI Spec generation. Finally, it has an optional details 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.

{\n  \"name\": \"add\",\n  \"description\": \"Add two numbers together\",\n  \"params\": [],\n  \"returns\": [],\n  \"details\": {}\n}\n
"},{"location":"reference/firefly_interface_format/#event","title":"Event","text":"

What goes into the events array is very similar. It is also a JSON object that has a name and a list of params. The difference is that events don't have returns. Arguments that are passed to the event when it is emitted are in params. It also has an optional description which can be helpful in OpenAPI Spec generation. Finally, it has an optional details 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.

{\n  \"name\": \"added\",\n  \"description\": \"An event that occurs when numbers have been added\",\n  \"params\": [],\n  \"details\": {}\n}\n
"},{"location":"reference/firefly_interface_format/#param","title":"Param","text":"

Both methods, and events have lists of params or returns, and the type of JSON object that goes in each of these arrays is the same. It is simply a JSON object with a name and a schema. There is also an optional details field that is passed to the blockchain plugin for blockchain specific requirements.

{\n  \"name\": \"x\",\n  \"schema\": {\n    \"type\": \"integer\",\n    \"details\": {}\n  }\n}\n
"},{"location":"reference/firefly_interface_format/#schema","title":"Schema","text":"

The param schema 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.

The schema field accepts JSON Schema (version 2020-12) with several additional requirements:

  • A type field is always mandatory
  • The list of valid types is:
  • boolean
  • integer
  • string
  • object
  • array
  • Blockchain plugins can add their own specific requirements to this list of validation rules

NOTE: Floats or decimals are not currently accepted because certain underlying blockchains (e.g. Ethereum) only allow integers

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 details field, if there is a compatible type mapping between the two.

"},{"location":"reference/firefly_interface_format/#schema-details","title":"Schema details","text":"

The details field is quite important in some cases. Because the details 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 details field.

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:

{\n  \"type\": \"uint256\",\n  \"internalType\": \"uint256\",\n  \"indexed\": false\n}\n
"},{"location":"reference/firefly_interface_format/#automated-generation-of-firefly-interfaces","title":"Automated generation of FireFly Interfaces","text":"

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.

For an example of using this endpoint with a specific Ethereum contract, please see the Tutorial to Work with custom smart contracts.

"},{"location":"reference/firefly_interface_format/#full-example","title":"Full Example","text":"

Putting it all together, here is a full example of the FireFly Interface format with all the fields filled in:

{\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
"},{"location":"reference/idempotency/","title":"Idempotency Keys","text":""},{"location":"reference/idempotency/#idempotency","title":"Idempotency","text":"

The transaction submission REST APIs of Hyperledger FireFly are idempotent.

Idempotent APIs allow an application to safely submit a request multiple times, and for the transaction to only be accepted and executed once.

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.

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.

In order for Hyperledger FireFly to deduplicate transactions, and make them idempotent, the application must supply an idempotencyKey on each API request.

"},{"location":"reference/idempotency/#firefly-idempotency-keys","title":"FireFly Idempotency Keys","text":"

The caller of the API specifies its own unique identifier (an arbitrary string up to 256 characters) that uniquely identifies the request, in the idempotencyKey field of the API.

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 409 Conflict HTTP code.

Examples of how an app might construct such an idempotencyKey include:

  • Unique business identifiers from the request that comes into its API up-stream - passing idempotency along the chain
  • 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.

    Be careful of cases where the business data might not be unique - like a transfer of 10 coins from A to B.

    Such a transfer could happen multiple times, and each would be a separate business transaction.

    Where as transfer with invoice number abcd1234 of 10 coins from A to B would be assured to be unique.

  • A unique identifier of a business transaction generated within the application and stored in its database before submission

    This moves the challenge up one layer into your application. How does that unique ID get generated? Is that itself idempotent?

"},{"location":"reference/idempotency/#operation-idempotency","title":"Operation Idempotency","text":"

FireFly provides an idempotent interface downstream to connectors.

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.

Well formed connectors honor this idempotency key internally, ensuring that the end-to-end transaction submission is idempotent.

Key examples of such connectors are EVMConnect and others built on the Blockchain Connector Toolkit.

When an operation is retried automatically, the same idempotency key is re-used to avoid resubmission.

"},{"location":"reference/idempotency/#short-term-retry","title":"Short term retry","text":"

The FireFly core uses standard HTTP request code to communicate with all connector APIs.

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.

See Configuration Reference for more information.

"},{"location":"reference/idempotency/#administrative-operation-retry","title":"Administrative operation retry","text":"

The operations/{operationId}/retry API can be called administratively to resubmit a transaction that has reached Failed status, or otherwise been determined by an operator/monitor to be unrecoverable within the connector.

In this case, the previous operation is marked Retried, a new operation ID is allocated, and the operation is re-submitted to the connector with this new ID.

"},{"location":"reference/identities/","title":"Identities","text":""},{"location":"reference/identities/#overview","title":"Overview","text":"

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.

"},{"location":"reference/identities/#types-of-identities","title":"Types of Identities","text":"

There are three types of identities:

"},{"location":"reference/identities/#org","title":"org","text":"

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.

The root organization name and key must be defined in the FireFly config (once for every multi-party system). It can be claimed with a POST to /network/organizations/self.

Organizations may have child identities of any type.

"},{"location":"reference/identities/#node","title":"node","text":"

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

The node name must be defined in the FireFly config (once for every multi-party system). It can be claimed with a POST to /network/nodes/self.

Nodes must be a child of an organization, and cannot have any child identities of their own.

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.

"},{"location":"reference/identities/#custom","title":"custom","text":"

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.

They can only have child identities which are also of type \"custom\".

"},{"location":"reference/identities/#identity-claims","title":"Identity Claims","text":"

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.

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.

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.

"},{"location":"reference/identities/#messaging","title":"Messaging","text":"

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.

"},{"location":"reference/identities/#sender","title":"Sender","text":"

When sending a message, the on-chain identity of the sender is controlled by the author and key fields.

  • If both are blank, the root organization is assumed.
  • If author 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 key.
  • If key 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 author.
  • If author and key are both specified, they will be used as-is (can be used to send private messages with an unregistered blockchain key).

The resolved key will be used to sign the blockchain transaction, which establishes the sender's on-chain identity.

The sender's off-chain identity is always controlled by the node.name from the config along with the data exchange plugin.

"},{"location":"reference/identities/#recipients","title":"Recipients","text":"

When specifying private message recipients, each one has an identity and a node.

  • If identity alone is specified, it should be the DID of an org or custom identity. The first node owned by that identity or one of its ancestors will be automatically selected.
  • If both identity and node are specified, they will be used as-is. The node should be a child of the given identity or one of its ancestors.

The node in this case will control how the off-chain portion of the message is routed via data exchange.

"},{"location":"reference/identities/#verification","title":"Verification","text":"

When a message is received, FireFly verifies the following:

  • The sender's author and key are specified in the message. The author must be a known org or custom identity. The key must match the blockchain key that was used to sign the on-chain portion of the message. For broadcast messages, the key must match the registered verifier for the author.
  • For private messages, the sending node (as reported by data exchange) must be a known node identity which is a child of the message's author identity or one of its ancestors. The combination of the author identity and the node must also be found in the message group.

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

"},{"location":"reference/namespaces/","title":"Namespaces","text":""},{"location":"reference/namespaces/#introduction-to-namespaces","title":"Introduction to Namespaces","text":"

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:

  • Plugin and infrastructure components
  • API security
  • Identity broadcasting
  • On-chain data indexing
  • How datatypes, locations of on-chain contrats, etc. should be shared

They can be thought of in two basic modes:

"},{"location":"reference/namespaces/#multi-party-namespaces","title":"Multi-party Namespaces","text":"

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.

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.

"},{"location":"reference/namespaces/#gateway-namespaces","title":"Gateway Namespaces","text":"

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.

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.

"},{"location":"reference/namespaces/#configuration","title":"Configuration","text":"

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.

Below is an example plugin and namespace configuration containing both a multi-party and gateway namespace:

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

The namespaces.predefined object contains the follow sub-keys:

  • defaultKey is a blockchain key used to sign transactions when none is specified (in multi-party mode, defaults to the org key)
  • plugins is an array of plugin names to be activated for this namespace (defaults to all available plugins if omitted)
  • multiparty.networkNamespace 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 name)
  • multiparty.enabled 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 org section at the root)
  • multiparty.org is the root org identity for this multi-party namespace (containing name, description, and key)
  • multiparty.node is the local node identity for this multi-party namespace (containing name and description)
  • multiparty.contract is an array of objects describing the location(s) of a FireFly multi-party smart contract. Its children are blockchain-agnostic location and firstEvent 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.
"},{"location":"reference/namespaces/#config-restrictions","title":"Config Restrictions","text":"
  • name must be unique on this node
  • for historical reasons, \"ff_system\" is a reserved string and cannot be used as a name or multiparty.networkNamespace
  • a database plugin is required for every namespace
  • if multiparty.enabled is true, plugins must include one each of blockchain, dataexchange, and sharedstorage
  • if multiparty.enabled is false, plugins must not include dataexchange or sharedstorage
  • at most one of each type of plugin is allowed per namespace, except for tokens (which may have many per namespace)

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.

"},{"location":"reference/namespaces/#definitions","title":"Definitions","text":"

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.

"},{"location":"reference/namespaces/#local-definitions","title":"Local Definitions","text":"

The following are all \"definition\" types in FireFly:

  • datatype
  • group
  • token pool
  • contract interface
  • contract API
  • organization (deprecated)
  • node (deprecated)
  • identity claim
  • identity verification
  • identity update

For gateway namespaces, the APIs which create these definitions will become an immediate local database insert, instead of performing a broadcast. Additional caveats:

  • identities in this mode will not undergo any claim/verification process, but will be created and stored locally
  • datatypes and groups will not be supported, as they are only useful in the context of messaging (which is disabled in gateway namespaces)
"},{"location":"reference/tls/","title":"TLS","text":""},{"location":"reference/tls/#tls-overview","title":"TLS Overview","text":"

To enable TLS in Firefly, there is a configuration available to provide certificates and keys.

The common configuration is as such:

tls:\n  enabled: true/false # Toggle on or off TLS\n  caFile: <path to the CA file you want the client or server to trust>\n  certFile: <path to the cert file you want the client or server to use when performing authentication in mTLS>\n  keyFile: <path to the priavte key file you want the client or server to use when performing  authentication in mTLS>\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

NOTE The CAs, certificates and keys have to be in PEM format.

"},{"location":"reference/tls/#configuring-tls-for-the-api-server","title":"Configuring TLS for the API server","text":"

Using the above configuration, we can place it under the http config and enable TLS or mTLS for any API call.

See this config section for details

"},{"location":"reference/tls/#configuring-tls-for-the-webhooks","title":"Configuring TLS for the webhooks","text":"

Using the above configuration, we can place it under the events.webhooks config and enable TLS or mTLS for any webhook call.

See this config section for details

"},{"location":"reference/tls/#configuring-clients-and-websockets","title":"Configuring clients and websockets","text":"

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.

For example, if you wish to configure the ethereum blockchain connector with TLS you would look at this config section

For more clients, search in the configuration reference for a TLS section.

"},{"location":"reference/tls/#enhancing-validation-of-certificates","title":"Enhancing validation of certificates","text":"

In the case where we want to verify that a specific client certificate has certain attributes we can use the requiredDNAtributes 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

"},{"location":"reference/microservices/fftokens/","title":"fftokens","text":""},{"location":"reference/microservices/fftokens/#overview","title":"Overview","text":"

fftokens is a protocol that can be implemented by token connector runtimes in order to be usable by the fftokens plugin in FireFly.

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.

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

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.

"},{"location":"reference/microservices/fftokens/#http-apis","title":"HTTP APIs","text":"

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 /api/v1 prefix.

"},{"location":"reference/microservices/fftokens/#post-createpool","title":"POST /createpool","text":"

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 config).

In a multiparty network, this operation will only be performed by one of the parties, and FireFly will broadcast the result to the others.

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

Request

{\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
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.

Response

HTTP 200: pool creation was successful, and the pool details are returned in the response.

See Response Types: Token Pool

HTTP 202: request was accepted, but pool will be created asynchronously, with \"receipt\" and \"token-pool\" events sent later on the websocket.

See Response Types: Async Request

"},{"location":"reference/microservices/fftokens/#post-activatepool","title":"POST /activatepool","text":"

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.

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 poolLocator and config information passed in to this call, the pool should not get confirmed.

Request

{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"poolData\": \"extra-pool-info\",\n  \"config\": {}\n}\n
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 config object that was passed when the pool was created.

Response

HTTP 200: pool activation was successful, and the pool details are returned in the response.

See Response Types: Token Pool

HTTP 202: request was accepted, but pool will be activated asynchronously, with \"receipt\" and \"token-pool\" events sent later on the websocket.

See Response Types: Async Request

HTTP 204: activation was successful - no separate receipt will be delivered, but \"token-pool\" event will be sent later on the websocket.

No body

"},{"location":"reference/microservices/fftokens/#post-deactivatepool","title":"POST /deactivatepool","text":"

Deactivate a token pool to stop receiving events and delete all blockchain listeners related to that pool.

Request

{\n  \"namespace\": \"default\",\n  \"poolLocator\": \"id=F1\",\n  \"poolData\": \"extra-pool-info\",\n  \"config\": {}\n}\n
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.

Response

HTTP 204: deactivation was successful, and one or more listeners were deleted.

No body

HTTP 404: no blockchain listeners were found for the given pool information.

No body

"},{"location":"reference/microservices/fftokens/#post-checkinterface","title":"POST /checkinterface","text":"

This is an optional (but recommended) API for token connectors. If implemented, support will be indicated by the presence of the interfaceFormat field in all Token Pool responses.

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.

Request

{\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
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 interfaceFormat 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 format.

Response

HTTP 200: interface was successfully parsed, and methods of interest are returned in the body.

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 interface parameter).

{\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
"},{"location":"reference/microservices/fftokens/#post-mint","title":"POST /mint","text":"

Mint new tokens.

Request

{\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
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 /checkinterface call.

Response

HTTP 202: request was accepted, but mint will occur asynchronously, with \"receipt\" and \"token-mint\" events sent later on the websocket.

See Response Types: Async Request

"},{"location":"reference/microservices/fftokens/#post-burn","title":"POST /burn","text":"

Burn tokens.

Request

{\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
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 /checkinterface call.

Response

HTTP 202: request was accepted, but burn will occur asynchronously, with \"receipt\" and \"token-burn\" events sent later on the websocket.

See Response Types: Async Request

"},{"location":"reference/microservices/fftokens/#post-transfer","title":"POST /transfer","text":"

Transfer tokens from one address to another.

Request

{\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
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 /checkinterface call.

Response

HTTP 202: request was accepted, but transfer will occur asynchronously, with \"receipt\" and \"token-transfer\" events sent later on the websocket.

See Response Types: Async Request

"},{"location":"reference/microservices/fftokens/#post-approval","title":"POST /approval","text":"

Approve another identity to manage tokens.

Request

{\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
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 /checkinterface call.

Response

HTTP 202: request was accepted, but approval will occur asynchronously, with \"receipt\" and \"token-approval\" events sent later on the websocket.

See Response Types: Async Request

"},{"location":"reference/microservices/fftokens/#websocket-commands","title":"Websocket Commands","text":"

In order to start listening for events on a certain namespace, the client needs to send the start command. Clients should send this command every time they connect, or after an automatic reconnect.

{\n  \"type\": \"start\",\n  \"namespace\": \"default\"\n}\n
"},{"location":"reference/microservices/fftokens/#websocket-events","title":"Websocket Events","text":"

A connector should expose a websocket at /api/ws. All emitted websocket events are a JSON string of the form:

{\n  \"id\": \"event-id\",\n  \"event\": \"event-name\",\n  \"data\": {}\n}\n

The event name will match one of the names listed below, and the data payload will correspond to the linked response object.

All events except the receipt event must be acknowledged by sending an ack of the form:

{\n  \"event\": \"ack\",\n  \"data\": {\n    \"id\": \"event-id\"\n  }\n}\n

Many messages may also be batched into a single websocket event of the form:

{\n  \"id\": \"event-id\",\n  \"event\": \"batch\",\n  \"data\": {\n    \"events\": [\n      {\n        \"event\": \"event-name\",\n        \"data\": {}\n      },\n      ...\n    ]\n  }\n}\n

Batched messages must be acked all at once using the ID of the batch.

"},{"location":"reference/microservices/fftokens/#receipt","title":"receipt","text":"

An asynchronous operation has completed.

See Response Types: Receipt

"},{"location":"reference/microservices/fftokens/#token-pool","title":"token-pool","text":"

A new token pool has been created or activated.

See Response Types: Token Pool

"},{"location":"reference/microservices/fftokens/#token-mint","title":"token-mint","text":"

Tokens have been minted.

See Response Types: Token Transfer

"},{"location":"reference/microservices/fftokens/#token-burn","title":"token-burn","text":"

Tokens have been burned.

See Response Types: Token Transfer

"},{"location":"reference/microservices/fftokens/#token-transfer","title":"token-transfer","text":"

Tokens have been transferred.

See Response Types: Token Transfer

"},{"location":"reference/microservices/fftokens/#token-approval","title":"token-approval","text":"

Token approvals have changed.

See Response Types: Token Approval

"},{"location":"reference/microservices/fftokens/#response-types","title":"Response Types","text":""},{"location":"reference/microservices/fftokens/#async-request","title":"Async Request","text":"

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.

{\n  \"id\": \"b84ab27d-0d50-42a6-9c26-2fda5eb901ba\"\n}\n
"},{"location":"reference/microservices/fftokens/#receipt_1","title":"Receipt","text":"
  \"headers\": {\n    \"type\": \"\",\n    \"requestId\": \"\"\n  }\n  \"transactionHash\": \"\",\n  \"errorMessage\": \"\"\n}\n
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":"
{\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
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 /checkinterface 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":"

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.

{\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
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":"
{\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
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":"

A batch bundles a number of off-chain messages, with associated data, into a single payload for broadcast or private transfer.

This allows the transfer of many messages (hundreds) to be backed by a single blockchain transaction. Thus making very efficient use of the blockchain.

The same benefit also applies to the off-chain transport mechanism.

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.

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.

"},{"location":"reference/types/batch/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/batch/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID of the batch UUID type The type of the batch FFEnum:\"broadcast\"\"private\" namespace The namespace of the batch string node The UUID of the node that generated the batch UUID group The privacy group the batch is sent to, for private batches Bytes32 created The time the batch was sealed FFTime author The DID of identity of the submitter string key The on-chain signing key used to sign the transaction string hash The hash of the manifest of the batch Bytes32 payload Batch.payload BatchPayload"},{"location":"reference/types/batch/#batchpayload","title":"BatchPayload","text":"Field Name Description Type tx BatchPayload.tx TransactionRef messages BatchPayload.messages Message[] data BatchPayload.data Data[]"},{"location":"reference/types/batch/#transactionref","title":"TransactionRef","text":"Field Name Description Type type The type of the FireFly transaction FFEnum: id The UUID of the FireFly transaction UUID"},{"location":"reference/types/blockchainevent/","title":"BlockchainEvent","text":"

Blockchain Events are detected by the blockchain plugin:

  1. When a ContractListener has been configured against any custom smart contract through the FireFly API
  2. 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
  3. 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).
"},{"location":"reference/types/blockchainevent/#protocol-id","title":"Protocol ID","text":"

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.

How to describe that position contains blockchain specifics - depending on how a particular blockchain represents transactions, blocks and events (or \"logs\").

So FireFly is flexible with a string protocolId 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.

An example protocolId string is: 000000000041/000020/000003

  • 000000000041 - this is the block number
  • 000020 - this is the transaction index within that block
  • 000003 - this is the event (/log) index within that transaction

The string is alphanumerically sortable as a plain string;

Sufficient zero padding is included at each layer to support future expansion without creating a string that would no longer sort correctly.

"},{"location":"reference/types/blockchainevent/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/blockchainevent/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID assigned to the event by FireFly UUID source The blockchain plugin or token service that detected the event string namespace The namespace of the listener that detected this blockchain event string name The name of the event in the blockchain smart contract string listener The UUID of the listener that detected this event, or nil for built-in events in the system namespace UUID protocolId An alphanumerically sortable string that represents this event uniquely on the blockchain (convention for plugins is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) string output The data output by the event, parsed to JSON according to the interface of the smart contract JSONObject info Detailed blockchain specific information about the event, as generated by the blockchain connector JSONObject timestamp The time allocated to this event by the blockchain. This is the block timestamp for most blockchain connectors FFTime tx 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 BlockchainTransactionRef"},{"location":"reference/types/blockchainevent/#blockchaintransactionref","title":"BlockchainTransactionRef","text":"Field Name Description Type type The type of the FireFly transaction FFEnum: id The UUID of the FireFly transaction UUID blockchainId The blockchain transaction ID, in the format specific to the blockchain involved in the transaction. Not all FireFly transactions include a blockchain string"},{"location":"reference/types/contractapi/","title":"ContractAPI","text":"

Contract APIs provide generated REST APIs for on-chain smart contracts.

API endpoints are generated to invoke or perform query operations against each of the functions/methods implemented by the smart contract.

API endpoints are also provided to add listeners to the events of that smart contract.

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 blockchain_event_received) that are emitted for each detected blockchain event.

For more information see the Events reference section.

"},{"location":"reference/types/contractapi/#url","title":"URL","text":"

The base path for your Contract API is:

  • /api/v1/namespaces/{ns}/apis/{apiName}

For the default namespace, this can be shortened to:

  • /api/v1/apis/{apiName}
"},{"location":"reference/types/contractapi/#firefly-interface-ffi-and-on-chain-location","title":"FireFly Interface (FFI) and On-chain Location","text":"

Contract APIs are registered against:

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

  2. An optional location 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 address of the Smart Contract for an Ethereum based blockchain, or the name and channel for a Hyperledger Fabric based blockchain.

If the location is not specified on creation of the Contract API, then it must be specified on each API call made to the Contract API endpoints.

"},{"location":"reference/types/contractapi/#openapi-v3-swagger-definitions","title":"OpenAPI V3 / Swagger Definitions","text":"

Each Contract API comes with an OpenAPI V3 / Swagger generated definition, which can be downloaded from:

  • /api/v1/namespaces/{namespaces}/apis/{apiName}/api/swagger.json
"},{"location":"reference/types/contractapi/#swagger-ui","title":"Swagger UI","text":"

A browser / exerciser UI for your API is also available on:

  • /api/v1/namespaces/{namespaces}/apis/{apiName}/api
"},{"location":"reference/types/contractapi/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/contractapi/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID of the contract API UUID namespace The namespace of the contract API string interface Reference to the FireFly Interface definition associated with the contract API FFIReference location 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 JSONAny name The name that is used in the URL to access the API string networkName The published name of the API within the multiparty network string message The UUID of the broadcast message that was used to publish this API to the network UUID urls The URLs to use to access the API ContractURLs published Indicates if the API is published to other members of the multiparty network bool"},{"location":"reference/types/contractapi/#ffireference","title":"FFIReference","text":"Field Name Description Type id The UUID of the FireFly interface UUID name The name of the FireFly interface string version The version of the FireFly interface string"},{"location":"reference/types/contractapi/#contracturls","title":"ContractURLs","text":"Field Name Description Type api The URL to use to invoke the API string openapi The URL to download the OpenAPI v3 (Swagger) description for the API generated in JSON or YAML format string ui The URL to use in a web browser to access the SwaggerUI explorer/exerciser for the API string"},{"location":"reference/types/contractlistener/","title":"ContractListener","text":"

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.

Check out the Custom Contracts Tutorial for a walk-through of how to set up listeners for the events from your smart contracts.

See below for a deep dive into the format of contract listeners and important concepts to understand when managing them.

"},{"location":"reference/types/contractlistener/#event-filters","title":"Event filters","text":""},{"location":"reference/types/contractlistener/#multiple-filters","title":"Multiple filters","text":"

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:

  • a reference to a specific blockchain event to listen for
  • (optional) a specific location/address to listen from
  • a connector-specific signature (generated from the event and the location)

In addition to this list of multiple filters, the listener specifies a single topic to identify the stream of events.

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.

"},{"location":"reference/types/contractlistener/#single-filter","title":"Single filter","text":"

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:

  • a reference to a specific blockchain event to listen for
  • (optional) a specific location/address to listen from
  • a connector-specific signature (generated from the event), which allows you to easily identify and search for the contact listener for an event
  • a topic which determines the ordered stream that these events are part of

For backwards compatibility, this format is still supported by the API.

"},{"location":"reference/types/contractlistener/#signature-strings","title":"Signature strings","text":""},{"location":"reference/types/contractlistener/#string-format","title":"String format","text":"

Each filter is identified by a generated signature that matches a single event, and each contract listener is identified by a signature computed from its filters.

Ethereum provides a string standard for event signatures, of the form EventName(uint256,bytes). Prior to v1.3.1, the signature of each Ethereum contract listener would exactly follow this Ethereum format.

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 indexed. For example, while the following two Solidity events have the same signature, they are serialized differently due to the different placement of indexed parameters, and thus a listener must define both individually to be able to process them:

  • ERC-20 Transfer
event Transfer(address indexed _from, address indexed _to, uint256 _value)\n
  • ERC-721 Transfer
event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);\n

The two above are now expressed in the following manner by the Ethereum blockchain connector:

Transfer(address,address,uint256) [i=0,1]\nTransfer(address,address,uint256) [i=0,1,2]\n

The [i=] listing at the end of the signature indicates the position of all parameters that are marked as indexed.

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:

  • Each filter signature is a combination of the location and the specific connector event signature, such as 0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]
  • Each contract listener signature is a concatenation of all the filter signatures, separated by ;
"},{"location":"reference/types/contractlistener/#duplicate-filters","title":"Duplicate filters","text":"

FireFly restricts the creation of a contract listener containing duplicate filters.

This includes the special case where one filter is a superset of another filter, due to a wildcard location.

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.

"},{"location":"reference/types/contractlistener/#duplicate-listeners","title":"Duplicate listeners","text":"

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.

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.

"},{"location":"reference/types/contractlistener/#backwards-compatibility","title":"Backwards compatibility","text":"

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.

  • The response from all query APIs of listeners will continue to populate top-level event and location fields
  • The first entry from the filters array is duplicated to these fields
  • On input to create a new listener, the event and location fields are still supported
  • They function identically to supplying a filters array with a single entry
  • The signature field is preserved at the listener level
  • The format has been changed as described above
"},{"location":"reference/types/contractlistener/#input-formats","title":"Input formats","text":"

The two input formats supported when creating a contract listener are shown below.

Muliple Filters

{\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

One filter (old format)

{\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
"},{"location":"reference/types/contractlistener/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/contractlistener/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID of the smart contract listener UUID interface Deprecated: Please use 'interface' in the array of 'filters' instead FFIReference namespace The namespace of the listener, which defines the namespace of all blockchain events detected by this listener string name A descriptive name for the listener string backendId An ID assigned by the blockchain connector to this listener string location Deprecated: Please use 'location' in the array of 'filters' instead JSONAny created The creation time of the listener FFTime event Deprecated: Please use 'event' in the array of 'filters' instead FFISerializedEvent signature A concatenation of all the stringified signature of the event and location, as computed by the blockchain plugin string topic 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 string options Options that control how the listener subscribes to events from the underlying blockchain ContractListenerOptions filters 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. ListenerFilter[]"},{"location":"reference/types/contractlistener/#ffireference","title":"FFIReference","text":"Field Name Description Type id The UUID of the FireFly interface UUID name The name of the FireFly interface string version The version of the FireFly interface string"},{"location":"reference/types/contractlistener/#ffiserializedevent","title":"FFISerializedEvent","text":"Field Name Description Type name The name of the event string description A description of the smart contract event string params An array of event parameter/argument definitions FFIParam[] details Additional blockchain specific fields about this event from the original smart contract. Used by the blockchain plugin and for documentation generation. JSONObject"},{"location":"reference/types/contractlistener/#ffiparam","title":"FFIParam","text":"Field Name Description Type name The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract string schema 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 JSONAny"},{"location":"reference/types/contractlistener/#contractlisteneroptions","title":"ContractListenerOptions","text":"Field Name Description Type firstEvent 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' string"},{"location":"reference/types/contractlistener/#listenerfilter","title":"ListenerFilter","text":"Field Name Description Type event The definition of the event, either provided in-line when creating the listener, or extracted from the referenced FFI FFISerializedEvent location A blockchain specific contract identifier. For example an Ethereum contract address, or a Fabric chaincode name and channel JSONAny interface A reference to an existing FFI, containing pre-registered type information for the event FFIReference signature The stringified signature of the event and location, as computed by the blockchain plugin string"},{"location":"reference/types/data/","title":"Data","text":"

Data is a uniquely identified piece of data available for retrieval or transfer.

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.

An UUID is allocated to each data resource.

A hash is also calculated as follows:

  • If there is only data, the hash is of the value serialized as JSON with no additional whitespace (order of the keys is retained from the original upload order).
  • If there is only a blob attachment, the hash is of the blob data.
  • There is is both a blob and a value, then the hash is a hash of the concatenation of a hash of the value and a hash of the blob.
"},{"location":"reference/types/data/#value-json-data-stored-in-the-core-database","title":"Value - JSON data stored in the core database","text":"

Each data resource can contain a value, which is any JSON type. String, number, boolean, array or object. This value is stored directly in the FireFly database.

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

"},{"location":"reference/types/data/#datatype-validation-of-agreed-data-types","title":"Datatype - validation of agreed data types","text":"

A datatype can be associated with your data, causing FireFly to verify the value against a schema before accepting it (on upload, or receipt from another party in the network).

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.

More information in the Datatype section

"},{"location":"reference/types/data/#blob-binary-data-stored-via-the-data-exchange","title":"Blob - binary data stored via the Data Exchange","text":"

Data resources can also contain a blob 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.

A Data resource can contain both a value JSON payload, and a blob 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.

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 value, and it has a property called name, then this value forms part of the data hash (as does every field in the value) and is stored in a separately indexed blob.name field.

The upload REST API provides an autometa form field, which can be set to ask FireFly core to automatically set the value to contain the filename, size, and MIME type from the file upload.

"},{"location":"reference/types/data/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/data/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID of the data resource UUID validator The data validator type FFEnum: namespace The namespace of the data resource string hash The hash of the data resource. Derived from the value and the hash of any binary blob attachment Bytes32 created The creation time of the data resource FFTime datatype The optional datatype to use of validation of this data DatatypeRef value 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 JSONAny public 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.) string blob An optional hash reference to a binary blob attachment BlobRef"},{"location":"reference/types/data/#datatyperef","title":"DatatypeRef","text":"Field Name Description Type name The name of the datatype string version The version of the datatype. Semantic versioning is encouraged, such as v1.0.1 string"},{"location":"reference/types/data/#blobref","title":"BlobRef","text":"Field Name Description Type hash The hash of the binary blob data Bytes32 size The size of the binary data int64 name The name field from the metadata attached to the blob, commonly used as a path/filename, and indexed for search string path If a name is specified, this field stores the '/' prefixed and separated path extracted from the full name string public 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.) string"},{"location":"reference/types/datatype/","title":"Datatype","text":"

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.

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 message_rejected event (rather than message_confirmed event).

Currently JSON Schema validation of data is supported.

The system for defining datatypes is pluggable, to support other schemes in the future, such as XML Schema, or CSV, EDI etc.

"},{"location":"reference/types/datatype/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/datatype/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID of the datatype UUID message The UUID of the broadcast message that was used to publish this datatype to the network UUID validator The validator that should be used to verify this datatype FFEnum:\"json\"\"none\"\"definition\" namespace The namespace of the datatype. Data resources can only be created referencing datatypes in the same namespace string name The name of the datatype string version The version of the datatype. Multiple versions can exist with the same name. Use of semantic versioning is encourages, such as v1.0.1 string hash 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 Bytes32 created The time the datatype was created FFTime value The definition of the datatype, in the syntax supported by the validator (such as a JSON Schema definition) JSONAny"},{"location":"reference/types/event/","title":"Event","text":"

Every Event emitted by FireFly shares a common structure.

See Events for a reference for how the overall event bus in Hyperledger FireFly operates, and descriptions of all the sub-categories of events.

"},{"location":"reference/types/event/#sequence","title":"Sequence","text":"

A local sequence 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.

"},{"location":"reference/types/event/#reference","title":"Reference","text":"

Events have a reference to the UUID of an object that is the subject of the event, such as a detailed Blockchain Event, or an off-chain Message.

When events are delivered to your application, the reference field is automatically retrieved and included in the JSON payload that is delivered to your application.

You can use the ?fetchreferences query parameter on API calls to request the same in-line JSON payload be included in query results.

The type of the reference also determines what subscription filters apply when performing server-side filters.

Here is the mapping between event types, and the object that you find in the reference field.

"},{"location":"reference/types/event/#correlator","title":"Correlator","text":"

For some event types, there is a secondary reference to an object that is associated with the event. This is set in a correlator field on the Event, but is not automatically fetched. This field is primarily used for the confirm option on API calls to allow FireFly to determine when a request has succeeded/failed.

"},{"location":"reference/types/event/#topic","title":"Topic","text":"

Events have a topic, 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.

For example when you send a Message, you set the topics you want that message to apply to, and FireFly ensures a consistent global order between all parties that receive that message.

"},{"location":"reference/types/event/#transaction","title":"Transaction","text":"

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.

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

Note that some events cannot be tagged with a Transaction ID:

  • Blockchain events, unless they were part of a batch-pin transaction for transfer of a message
  • Token transfers/approvals, unless they had a message transfer associated with them (and included a data payload in the event they emitted)
"},{"location":"reference/types/event/#reference-topic-and-correlator-by-event-type","title":"Reference, Topic and Correlator by Event Type","text":"Types Reference Topic Correlator transaction_submitted Transaction transaction.type message_confirmedmessage_rejected Message message.header.topics[i]* message.header.cid token_pool_confirmed TokenPool tokenPool.id token_pool_op_failed Operation tokenPool.id tokenPool.id token_transfer_confirmed TokenTransfer tokenPool.id token_transfer_op_failed Operation tokenPool.id tokenTransfer.localId token_approval_confirmed TokenApproval tokenPool.id token_approval_op_failed Operation tokenPool.id tokenApproval.localId namespace_confirmed Namespace \"ff_definition\" datatype_confirmed Datatype \"ff_definition\" identity_confirmedidentity_updated Identity \"ff_definition\" contract_interface_confirmed FFI \"ff_definition\" contract_api_confirmed ContractAPI \"ff_definition\" blockchain_event_received BlockchainEvent From listener ** blockchain_invoke_op_succeeded Operation blockchain_invoke_op_failed Operation blockchain_contract_deploy_op_succeeded Operation blockchain_contract_deploy_op_failed Operation
  • A separate event is emitted for each topic associated with a Message.

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

"},{"location":"reference/types/event/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/event/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID assigned to this event by your local FireFly node UUID sequence 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) int64 type 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 FFEnum:\"transaction_submitted\"\"message_confirmed\"\"message_rejected\"\"datatype_confirmed\"\"identity_confirmed\"\"identity_updated\"\"token_pool_confirmed\"\"token_pool_op_failed\"\"token_transfer_confirmed\"\"token_transfer_op_failed\"\"token_approval_confirmed\"\"token_approval_op_failed\"\"contract_interface_confirmed\"\"contract_api_confirmed\"\"blockchain_event_received\"\"blockchain_invoke_op_succeeded\"\"blockchain_invoke_op_failed\"\"blockchain_contract_deploy_op_succeeded\"\"blockchain_contract_deploy_op_failed\" namespace The namespace of the event. Your application must subscribe to events within a namespace string reference 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 UUID correlator 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 UUID tx The UUID of a transaction that is event is part of. Not all events are part of a transaction UUID topic 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 string created 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 FFTime"},{"location":"reference/types/ffi/","title":"FFI","text":"

See FireFly Interface Format

"},{"location":"reference/types/ffi/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/ffi/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID of the FireFly interface (FFI) smart contract definition UUID message The UUID of the broadcast message that was used to publish this FFI to the network UUID namespace The namespace of the FFI string name The name of the FFI - usually matching the smart contract name string networkName The published name of the FFI within the multiparty network string description A description of the smart contract this FFI represents string version A version for the FFI - use of semantic versioning such as 'v1.0.1' is encouraged string methods An array of smart contract method definitions FFIMethod[] events An array of smart contract event definitions FFIEvent[] errors An array of smart contract error definitions FFIError[] published Indicates if the FFI is published to other members of the multiparty network bool"},{"location":"reference/types/ffi/#ffimethod","title":"FFIMethod","text":"Field Name Description Type id The UUID of the FFI method definition UUID interface The UUID of the FFI smart contract definition that this method is part of UUID name The name of the method string namespace The namespace of the FFI string pathname 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 string description A description of the smart contract method string params An array of method parameter/argument definitions FFIParam[] returns An array of method return definitions FFIParam[] details Additional blockchain specific fields about this method from the original smart contract. Used by the blockchain plugin and for documentation generation. JSONObject"},{"location":"reference/types/ffi/#ffiparam","title":"FFIParam","text":"Field Name Description Type name The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract string schema 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 JSONAny"},{"location":"reference/types/ffi/#ffievent","title":"FFIEvent","text":"Field Name Description Type id The UUID of the FFI event definition UUID interface The UUID of the FFI smart contract definition that this event is part of UUID namespace The namespace of the FFI string pathname 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 string signature The stringified signature of the event, as computed by the blockchain plugin string name The name of the event string description A description of the smart contract event string params An array of event parameter/argument definitions FFIParam[] details Additional blockchain specific fields about this event from the original smart contract. Used by the blockchain plugin and for documentation generation. JSONObject"},{"location":"reference/types/ffi/#ffiparam_1","title":"FFIParam","text":"Field Name Description Type name The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract string schema 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 JSONAny"},{"location":"reference/types/ffi/#ffierror","title":"FFIError","text":"Field Name Description Type id The UUID of the FFI error definition UUID interface The UUID of the FFI smart contract definition that this error is part of UUID namespace The namespace of the FFI string pathname The unique name allocated to this error within the FFI for use on URL paths string signature The stringified signature of the error, as computed by the blockchain plugin string name The name of the error string description A description of the smart contract error string params An array of error parameter/argument definitions FFIParam[]"},{"location":"reference/types/ffi/#ffiparam_2","title":"FFIParam","text":"Field Name Description Type name The name of the parameter. Note that parameters must be ordered correctly on the FFI, according to the order in the blockchain smart contract string schema 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 JSONAny"},{"location":"reference/types/group/","title":"Group","text":"

A privacy group is a list of identities that should receive a private communication.

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.

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.

The sender is included automatically in the group when members are specified in-line, if it is omitted.

"},{"location":"reference/types/group/#group-identity-hash","title":"Group identity hash","text":"

The identifying hash for a group is determined as follows:

  • All identities are resolved to their DID.
  • An organization name or identity UUID can be used on input
  • The UUID of the node that should receive the data for each participant is determined (if not specified).
  • The first node found that is in the same identity hierarchy as the participant identity, will be chosen.
  • The list of participants is ordered by DID, with de-duplication of any identities.
  • The namespace, name, and members array are then serialized into a JSON object, without whitespace.
  • A SHA256 hash of the JSON object is calculated
"},{"location":"reference/types/group/#private-messaging-architecture","title":"Private messaging architecture","text":"

The mechanism that keeps data private and ordered, without leaking data to the blockchain, is summarized in the below diagram.

The key points are:

  • Data is sent off-chain to all participants via the Data Exchange plugin
  • The Data Exchange is responsible for encryption and off-chain identity verification
  • Only parties that are involved in the privacy group receive the data
  • Other parties are only able to view the blockchain transaction
  • The hash and member list of the group are not shared outside of the privacy group
  • The name of the group can be used as an additional salt in generation of the group hash
  • 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
  • The blockchain transaction is the source of truth for ordering
  • 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)
  • 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
  • The ordering context (topic+group) is combined with a nonce that is incremented for each individual sender, to form a message-specific hash.
  • 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)

See NextPin for more information on the structure used for storing the next expected masked context pin, for each member of the privacy group.

"},{"location":"reference/types/group/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/group/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type namespace The namespace of the group within the multiparty network string name The optional name of the group, allowing multiple unique groups to exist with the same list of recipients string members The list of members in this privacy group Member[] localNamespace The local namespace of the group string message The message used to broadcast this group privately to the members UUID hash The identifier hash of this group. Derived from the name and group members Bytes32 created The time when the group was first used to send a message in the network FFTime"},{"location":"reference/types/group/#member","title":"Member","text":"Field Name Description Type identity The DID of the group member string node The UUID of the node that receives a copy of the off-chain message for the identity UUID"},{"location":"reference/types/identity/","title":"Identity","text":"

FireFly contains an address book of identities, which is managed in a decentralized way across a multi-party system through claim and verification system.

See FIR-12 for evolution that is happening to Hyperledger FireFly to allow:

  • Private address books that are not shared with other participants
  • Multiple address books backed by different chains, in the same node

Root identities are registered with only a claim - which is a signed transaction from a particular blockchain account, to bind a DID with a name that is unique within the network, to that signing key.

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.

When child identities are registered, a claim 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 verification that references the claim (by UUID) using the key verifier of the parent identity.

"},{"location":"reference/types/identity/#dids","title":"DIDs","text":"

FireFly has adopted the DID standard for representing identities. A \"DID Method\" name of firefly is used to represent that the built-in identity system of Hyperledger FireFly is being used to resolve these DIDs.

So an example FireFly DID for organization abcd1234 is:

  • did:firefly:org/abcd1234

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.

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.

"},{"location":"reference/types/identity/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/identity/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID of the identity UUID did The DID of the identity. Unique across namespaces within a FireFly network string type The type of the identity FFEnum:\"org\"\"node\"\"custom\" parent The UUID of the parent identity. Unset for root organization identities UUID namespace The namespace of the identity. Organization and node identities are always defined in the ff_system namespace string name The name of the identity. The name must be unique within the type and namespace string description A description of the identity. Part of the updatable profile information of an identity string profile A set of metadata for the identity. Part of the updatable profile information of an identity JSONObject messages References to the broadcast messages that established this identity and proved ownership of the associated verifiers (keys) IdentityMessages created The creation time of the identity FFTime updated The last update time of the identity profile FFTime"},{"location":"reference/types/identity/#identitymessages","title":"IdentityMessages","text":"Field Name Description Type claim The UUID of claim message UUID verification The UUID of claim message. Unset for root organization identities UUID update The UUID of the most recently applied update message. Unset if no updates have been confirmed UUID"},{"location":"reference/types/message/","title":"Message","text":"

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.

A message is made up of three sections:

  1. The header - a set of metadata that determines how the message is ordered, who should receive it, and how they should process it
  2. The data - an array of data attachments
  3. Status information - fields that are calculated independently by each node, and hence update as the message makes it way through the system
"},{"location":"reference/types/message/#hash","title":"Hash","text":"

Sections (1) and (2) are fixed once the message is sent, and a hash is generated that provides tamper protection.

The hash is a function of the header, and all of the data payloads. Calculated as follows:

  • The hash of each Data element is calculated individually
  • A JSON array of [{\"id\":\"{{DATA_UUID}}\",\"hash\":\"{{DATA_HASH}}\"}] is hashed, and that hash is stored in header.datahash
  • The header is serialized as JSON with the deterministic order (listed below) and hashed
  • JSON data is serialized without whitespace to hash it.
  • The hashing algorithm is SHA-256

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.

"},{"location":"reference/types/message/#tag","title":"Tag","text":"

The header.tag tells the processors of the message how it should be processed, and what data they should expect it to contain.

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

Every copy of the application that runs in the participants of the network should look at this tag to determine what logic to execute against it.

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.

"},{"location":"reference/types/message/#topics","title":"Topics","text":"

The header.topics 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 default topic is not recommended).

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.

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 & network links involved in that off-chain communication.

A \"stop the world\" approach to handling a single piece of missing data is not practical for a high volume production business network.

The ordering context is a function of:

  1. Whether the message is broadcast or private
  2. If it is private, the privacy group associated with the message
  3. The topic of the message

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.

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.

For your application, you should choose the most granular identifier you can for your topic 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:

  • A business transaction identifier - to ensure all data related to particular business transaction are processed in order
  • A globally agreed customer identifier - to ensure all data related to a particular business entity are processed in order
"},{"location":"reference/types/message/#using-multiple-topics","title":"Using multiple topics","text":"

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.

A synchronization point between two otherwise independent streams of communication.

To do this, simply specify two topics in the message you sent, and the message will be independently ordered against both of those topics.

You will also receive two events for the confirmation of that message, one for each topic.

Some examples:

  • Agreeing to join two previously separate business transactions with ids 000001 and 000002, by discarding business transaction 000001 as a duplicate
  • Specify topics: [\"000001\",\"000002\"] on the special merge message, and then from that point onwards you would only need to specify topics: [\"000002\"].
  • Agreeing to join two previously separate entities with id1 and id2, into a merged entity with id3.
  • Specify topics: [\"id1\",\"id2\",\"id3\"] on the special merge message, and then from that point onwards you would only need to specify topics: [\"id3\"].
"},{"location":"reference/types/message/#transaction-type","title":"Transaction type","text":"

By default messages are pinned to the blockchain, within a Batch.

For private messages, you can choose to disable this pinning by setting header.txtype: \"unpinned\".

Broadcast messages must be pinned to the blockchain.

"},{"location":"reference/types/message/#in-line-data","title":"In-line data","text":"

When sending a message you can specify the array of Data attachments in-line, as part of the same JSON payload.

For example, a minimal broadcast message could be:

{\n    \"data\": [\n        {\"value\": \"hello world\"}\n    ]\n}\n

When you send this message with /api/v1/namespaces/{ns}/messages/broadcast:

  • The header will be initialized with the default values, including txtype: \"batch_pin\"
  • The data[0] entry will be stored as a Data resource
  • The message will be assembled into a batch and broadcast
"},{"location":"reference/types/message/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/message/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type header The message header contains all fields that are used to build the message hash MessageHeader localNamespace The local namespace of the message string hash The hash of the message. Derived from the header, which includes the data hash Bytes32 batch The UUID of the batch in which the message was pinned/transferred UUID txid The ID of the transaction used to order/deliver this message UUID state The current state of the message FFEnum:\"staged\"\"ready\"\"sent\"\"pending\"\"confirmed\"\"rejected\"\"cancelled\" confirmed The timestamp of when the message was confirmed/rejected FFTime rejectReason If a message was rejected, provides details on the rejection reason string data The list of data elements attached to the message DataRef[] pins For private messages, a unique pin hash:nonce is assigned for each topic string[] idempotencyKey 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 IdempotencyKey"},{"location":"reference/types/message/#messageheader","title":"MessageHeader","text":"Field Name Description Type id The UUID of the message. Unique to each message UUID cid The correlation ID of the message. Set this when a message is a response to another message UUID type The type of the message FFEnum:\"definition\"\"broadcast\"\"private\"\"groupinit\"\"transfer_broadcast\"\"transfer_private\"\"approval_broadcast\"\"approval_private\" txtype The type of transaction used to order/deliver this message FFEnum:\"none\"\"unpinned\"\"batch_pin\"\"network_action\"\"token_pool\"\"token_transfer\"\"contract_deploy\"\"contract_invoke\"\"contract_invoke_pin\"\"token_approval\"\"data_publish\" author The DID of identity of the submitter string key The on-chain signing key used to sign the transaction string created The creation time of the message FFTime namespace The namespace of the message within the multiparty network string topics A message topic associates this message with an ordered stream of data. A custom topic should be assigned - using the default topic is discouraged string[] tag The message tag indicates the purpose of the message to the applications that process it string datahash A single hash representing all data in the message. Derived from the array of data ids+hashes attached to this message Bytes32 txparent The parent transaction that originally triggered this message TransactionRef"},{"location":"reference/types/message/#transactionref","title":"TransactionRef","text":"Field Name Description Type type The type of the FireFly transaction FFEnum: id The UUID of the FireFly transaction UUID"},{"location":"reference/types/message/#dataref","title":"DataRef","text":"Field Name Description Type id The UUID of the referenced data resource UUID hash The hash of the referenced data Bytes32"},{"location":"reference/types/namespace/","title":"Namespace","text":"

A namespace is a logical isolation domain for different applications, or tenants, that share the FireFly node.

Significant evolution of the Hyperledger FireFly namespace construct, is proposed under FIR-12

"},{"location":"reference/types/namespace/#example","title":"Example","text":"
{\n    \"name\": \"default\",\n    \"networkName\": \"default\",\n    \"description\": \"Default predefined namespace\",\n    \"created\": \"2022-05-16T01:23:16Z\"\n}\n
"},{"location":"reference/types/namespace/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type name The local namespace name string networkName The shared namespace name within the multiparty network string description A description of the namespace string created The time the namespace was created FFTime"},{"location":"reference/types/nextpin/","title":"NextPin","text":"

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.

This allows every member to maintain a global order of transactions within a topic in a privacy group, without leaking the same hash between the messages that are communicated in that group.

See Group for more information on privacy groups.

"},{"location":"reference/types/nextpin/#example","title":"Example","text":"
{\n    \"namespace\": \"ns1\",\n    \"context\": \"a25b65cfe49e5ed78c256e85cf07c96da938144f12fcb02fe4b5243a4631bd5e\",\n    \"identity\": \"did:firefly:org/example\",\n    \"hash\": \"00e55c63905a59782d5bc466093ead980afc4a2825eb68445bcf1312cc3d6de2\",\n    \"nonce\": 12345\n}\n
"},{"location":"reference/types/nextpin/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type namespace The namespace of the next-pin string context 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 Bytes32 identity The member of the privacy group the next-pin applies to string hash The unique masked pin string Bytes32 nonce The numeric index - which is monotonically increasing for each member of the privacy group int64"},{"location":"reference/types/operation/","title":"Operation","text":"

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.

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.

"},{"location":"reference/types/operation/#operation-status","title":"Operation status","text":"

When initially created an operation is in Initialized state. Once the operation has been successfully sent to its respective plugin to be processed its status moves to Pending state. This indicates that the plugin is processing the operation. The operation will then move to Succeeded or Failed state depending on the outcome.

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 Initialized state. Re-submitting the same FireFly API call using the same idempotency key will cause FireFly to re-submit the operation to its plugin.

"},{"location":"reference/types/operation/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/operation/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID of the operation UUID namespace The namespace of the operation string tx The UUID of the FireFly transaction the operation is part of UUID type The type of the operation FFEnum:\"blockchain_pin_batch\"\"blockchain_network_action\"\"blockchain_deploy\"\"blockchain_invoke\"\"sharedstorage_upload_batch\"\"sharedstorage_upload_blob\"\"sharedstorage_upload_value\"\"sharedstorage_download_batch\"\"sharedstorage_download_blob\"\"dataexchange_send_batch\"\"dataexchange_send_blob\"\"token_create_pool\"\"token_activate_pool\"\"token_transfer\"\"token_approval\" status The current status of the operation OpStatus plugin The plugin responsible for performing the operation string input The input to this operation JSONObject output Any output reported back from the plugin for this operation JSONObject error Any error reported back from the plugin for this operation string created The time the operation was created FFTime updated The last update time of the operation FFTime retry If this operation was initiated as a retry to a previous operation, this field points to the UUID of the operation being retried UUID"},{"location":"reference/types/operationwithdetail/","title":"OperationWithDetail","text":"

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 detail field.

"},{"location":"reference/types/operationwithdetail/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/operationwithdetail/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID of the operation UUID namespace The namespace of the operation string tx The UUID of the FireFly transaction the operation is part of UUID type The type of the operation FFEnum:\"blockchain_pin_batch\"\"blockchain_network_action\"\"blockchain_deploy\"\"blockchain_invoke\"\"sharedstorage_upload_batch\"\"sharedstorage_upload_blob\"\"sharedstorage_upload_value\"\"sharedstorage_download_batch\"\"sharedstorage_download_blob\"\"dataexchange_send_batch\"\"dataexchange_send_blob\"\"token_create_pool\"\"token_activate_pool\"\"token_transfer\"\"token_approval\" status The current status of the operation OpStatus plugin The plugin responsible for performing the operation string input The input to this operation JSONObject output Any output reported back from the plugin for this operation JSONObject error Any error reported back from the plugin for this operation string created The time the operation was created FFTime updated The last update time of the operation FFTime retry If this operation was initiated as a retry to a previous operation, this field points to the UUID of the operation being retried UUID detail 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":"

IDs are generated as UUID V4 globally unique identifiers

"},{"location":"reference/types/simpletypes/#fftime","title":"FFTime","text":"

Times are serialized to JSON on the API in RFC 3339 / ISO 8601 nanosecond UTC time for example 2022-05-05T21:19:27.454767543Z.

Note that JavaScript can parse this format happily into millisecond time with Date.parse().

Times are persisted as a nanosecond resolution timestamps in the database.

On input, and in queries, times can be parsed from RFC3339, or unix timestamps (second, millisecond or nanosecond resolution).

"},{"location":"reference/types/simpletypes/#ffbigint","title":"FFBigInt","text":"

Large integers of up to 256bits in size are common in blockchain, and handled in FireFly.

In JSON output payloads in FireFly, including events, they are serialized as strings (with base 10).

On input you can provide JSON string (string with an 0x prefix are parsed at base 16), or a JSON number.

Be careful when using JSON numbers, that the largest number that is safe to transfer using a JSON number is 2^53 - 1.

"},{"location":"reference/types/simpletypes/#jsonany","title":"JSONAny","text":"

Any JSON type. An object, array, string, number, boolean or null.

FireFly stores object data with the same field order as was provided on the input, but with any whitespace removed.

"},{"location":"reference/types/simpletypes/#jsonobject","title":"JSONObject","text":"

Any JSON Object. Must be an object, rather than an array or a simple type.

"},{"location":"reference/types/subscription/","title":"Subscription","text":"

Each Subscription tracks delivery of events to a particular application, and allows FireFly to ensure that messages are delivered reliably to that application.

"},{"location":"reference/types/subscription/#creating-a-subscription","title":"Creating a subscription","text":"

Before you can connect to a subscription, you must create it via the REST API.

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.

When creating a new subscription, you give it a name which is how you will refer to it when you connect.

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.

All subscriptions are created within a namespace, and automatically filter events to only those emitted within that namespace.

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.

"},{"location":"reference/types/subscription/#subscriptions-and-workload-balancing","title":"Subscriptions and workload balancing","text":"

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.

Each event is only delivered once to the subscription, regardless of how many instances of your application connect to FireFly.

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.

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.

"},{"location":"reference/types/subscription/#pluggable-transports","title":"Pluggable Transports","text":"

Hyperledger FireFly has two built-in transports for delivery of events to applications - WebSockets and Webhooks.

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.

"},{"location":"reference/types/subscription/#websockets","title":"WebSockets","text":"

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.

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.

A Java SDK is a roadmap item for the community.

"},{"location":"reference/types/subscription/#websocket-protocol","title":"WebSocket protocol","text":"

FireFly has a simple protocol on top of WebSockets:

  1. 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):
  2. Send a WSStart JSON payload
  3. Include a namespace and name query parameter in the URL when you connect, along with query params for other fields of WSStart
  4. One you have started your subscription, each event flows from the server, to your application as a JSON Event payload
  5. For each event you receive, you need to send a WSAck payload.
  6. Unless you specified autoack in step (1)

The SDK libraries for FireFly help you ensure you send the start payload each time your WebSocket reconnects.

"},{"location":"reference/types/subscription/#using-start-and-ack-explicitly","title":"Using start and ack explicitly","text":"

Here's an example websocat command showing an explicit start and ack.

$ 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

When creating your subscription, you can set readahead in order to ask FireFly to stream a number of messages to your application, ahead of receiving the acknowledgements.

readahead 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 ack for each event.

"},{"location":"reference/types/subscription/#auto-starting-via-url-query-and-autoack","title":"Auto-starting via URL query and autoack","text":"

Here's an example websocat where we use URL query parameters to avoid the need to send a start JSON payload.

We also use autoack so that events just keep flowing from the server.

$ websocat \"ws://localhost:5000/ws?namespace=default&name=docexample&autoack\"\n# ... events just keep arriving here, as the server-side auto-acknowledges\n#     the events as it delivers them to you.\n

Note using autoack 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.

"},{"location":"reference/types/subscription/#ephemeral-websocket-subscriptions","title":"Ephemeral WebSocket subscriptions","text":"

FireFly WebSockets provide a special option to create a subscription dynamically, that only lasts for as long as you are connected to the server.

We call these ephemeral subscriptions.

Here's an example websocat command showing an an ephemeral subscription - notice we don't specify a name for the subscription, and there is no need to have already created the subscription beforehand.

Here we also include an extra query parameter to set a server-side filter, to only include message events.

$ websocat \"ws://localhost:5000/ws?namespace=default&ephemeral&autoack&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

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.

"},{"location":"reference/types/subscription/#webhooks","title":"Webhooks","text":"

The Webhook transport allows FireFly to make HTTP calls against your application's API when events matching your subscription are emitted.

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.

Webhooks are great for serverless functions (AWS Lambda etc.), integrations with SaaS applications, and calling existing APIs.

The FireFly configuration options for a Webhook subscription are very flexible, allowing you to customize your HTTP requests as follows:

  • Set the HTTP request details:
  • Method, URL, query, headers and input body
  • Wait for a invocation of the back-end service, before acknowledging
  • To retry requests to your Webhook on a non-2xx HTTP status code or other error, you should enable and configure options.retry
  • The event is acknowledged once the request (with any retries), is completed - regardless of whether the outcome was a success or failure.
  • Use fastack to acknowledge against FireFly immediately and make multiple parallel calls to the HTTP API in a fire-and-forget fashion.
  • Set the HTTP request details dynamically from message_confirmed events:
  • Map data out of the first data element in message events
  • Requires withData to be set on the subscription, in addition to the input.* configuration options
  • Can automatically generate a \"reply\" message for message_confirmed events:
  • Maps the response body of the HTTP call to data in the reply message
  • Sets the cid and topic in the reply message to match the request
  • Sets a tag in the reply message, per the configuration, or dynamically based on a field in the input request data.
"},{"location":"reference/types/subscription/#batching-events","title":"Batching events","text":"

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 readAhead limit and an optional timeout can be specified to send the events when the batch hasn't filled.

To enable this set the following configuration under SubscriptionOptions

batch | 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. | bool |

batchTimeout | When batching is enabled, the optional timeout to send events even when the batch hasn't filled. Defaults to 2 seconds | string

NOTE: When batch is enabled, withData 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.

"},{"location":"reference/types/subscription/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/subscription/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID of the subscription UUID namespace The namespace of the subscription. A subscription will only receive events generated in the namespace of the subscription string name 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 string transport The transport plugin responsible for event delivery (WebSockets, Webhooks, JMS, NATS etc.) string filter Server-side filter to apply to events SubscriptionFilter options Subscription options SubscriptionOptions ephemeral 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 bool created Creation time of the subscription FFTime updated Last time the subscription was updated FFTime"},{"location":"reference/types/subscription/#subscriptionfilter","title":"SubscriptionFilter","text":"Field Name Description Type events Regular expression to apply to the event type, to subscribe to a subset of event types string message Filters specific to message events. If an event is not a message event, these filters are ignored MessageFilter transaction Filters specific to events with a transaction. If an event is not associated with a transaction, this filter is ignored TransactionFilter blockchainevent Filters specific to blockchain events. If an event is not a blockchain event, these filters are ignored BlockchainEventFilter topic 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 string topics Deprecated: Please use 'topic' instead string tag Deprecated: Please use 'message.tag' instead string group Deprecated: Please use 'message.group' instead string author Deprecated: Please use 'message.author' instead string"},{"location":"reference/types/subscription/#messagefilter","title":"MessageFilter","text":"Field Name Description Type tag Regular expression to apply to the message 'header.tag' field string group Regular expression to apply to the message 'header.group' field string author Regular expression to apply to the message 'header.author' field string"},{"location":"reference/types/subscription/#transactionfilter","title":"TransactionFilter","text":"Field Name Description Type type Regular expression to apply to the transaction 'type' field string"},{"location":"reference/types/subscription/#blockchaineventfilter","title":"BlockchainEventFilter","text":"Field Name Description Type name Regular expression to apply to the blockchain event 'name' field, which is the name of the event in the underlying blockchain smart contract string listener 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 string"},{"location":"reference/types/subscription/#subscriptionoptions","title":"SubscriptionOptions","text":"Field Name Description Type firstEvent 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' SubOptsFirstEvent readAhead 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 uint16 withData 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. bool batch 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. bool batchTimeout When batching is enabled, the optional timeout to send events even when the batch hasn't filled. string fastack Webhooks only: When true the event will be acknowledged before the webhook is invoked, allowing parallel invocations bool url Webhooks only: HTTP url to invoke. Can be relative if a base URL is set in the webhook plugin config string method Webhooks only: HTTP method to invoke. Default=POST string json Webhooks only: Whether to assume the response body is JSON, regardless of the returned Content-Type bool reply Webhooks only: Whether to automatically send a reply event, using the body returned by the webhook bool replytag Webhooks only: The tag to set on the reply message string replytx Webhooks only: The transaction type to set on the reply message string headers Webhooks only: Static headers to set on the webhook request `` query Webhooks only: Static query params to set on the webhook request `` tlsConfigName The name of an existing TLS configuration associated to the namespace to use string input Webhooks only: A set of options to extract data from the first JSON input data in the incoming message. Only applies if withData=true WebhookInputOptions retry Webhooks only: a set of options for retrying the webhook call WebhookRetryOptions httpOptions Webhooks only: a set of options for HTTP WebhookHTTPOptions"},{"location":"reference/types/subscription/#webhookinputoptions","title":"WebhookInputOptions","text":"Field Name Description Type query A top-level property of the first data input, to use for query parameters string headers A top-level property of the first data input, to use for headers string body A top-level property of the first data input, to use for the request body. Default is the whole first body string path A top-level property of the first data input, to use for a path to append with escaping to the webhook path string replytx A top-level property of the first data input, to use to dynamically set whether to pin the response (so the requester can choose) string"},{"location":"reference/types/subscription/#webhookretryoptions","title":"WebhookRetryOptions","text":"Field Name Description Type enabled Enables retry on HTTP calls, defaults to false bool count Number of times to retry the webhook call in case of failure int initialDelay Initial delay between retries when we retry the webhook call string maxDelay Max delay between retries when we retry the webhookcall string"},{"location":"reference/types/subscription/#webhookhttpoptions","title":"WebhookHTTPOptions","text":"Field Name Description Type proxyURL HTTP proxy URL to use for outbound requests to the webhook string tlsHandshakeTimeout The max duration to hold a TLS handshake alive string requestTimeout The max duration to hold a TLS handshake alive string maxIdleConns The max number of idle connections to hold pooled int idleTimeout The max duration to hold a HTTP keepalive connection between calls string connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted. string expectContinueTimeout See ExpectContinueTimeout in the Go docs string"},{"location":"reference/types/tokenapproval/","title":"TokenApproval","text":"

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.

The approved \"operator\" (or \"spender\") account might be a smart contract, or another individual.

FireFly provides APIs for initiating and tracking approvals, which token connectors integrate with the implementation of the underlying token.

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 subject field, combined with the active 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 \"active\": false, and the new approval is marked with \"active\": true

The token connector is responsible for the format of the subject field to reflect the owner / operator (spender) relationship.

"},{"location":"reference/types/tokenapproval/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/tokenapproval/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type localId The UUID of this token approval, in the local FireFly node UUID pool The UUID the token pool this approval applies to UUID connector 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 string key The blockchain signing key for the approval request. On input defaults to the first signing key of the organization that operates the node string operator The blockchain identity that is granted the approval string approved Whether this record grants permission for an operator to perform actions on the token balance (true), or revokes permission (false) bool info 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 JSONObject namespace The namespace for the approval, which must match the namespace of the token pool string protocolId An alphanumerically sortable string that represents this event uniquely with respect to the blockchain string subject A string identifying the parties and entities in the scope of this approval, as provided by the token connector string active Indicates if this approval is currently active (only one approval can be active per subject) bool message The UUID of a message that has been correlated with this approval using the data field of the approval in a compatible token connector UUID messageHash The hash of a message that has been correlated with this approval using the data field of the approval in a compatible token connector Bytes32 created The creation time of the token approval FFTime tx If submitted via FireFly, this will reference the UUID of the FireFly transaction (if the token connector in use supports attaching data) TransactionRef blockchainEvent The UUID of the blockchain event UUID config Input only field, with token connector specific configuration of the approval. See your chosen token connector documentation for details JSONObject"},{"location":"reference/types/tokenapproval/#transactionref","title":"TransactionRef","text":"Field Name Description Type type The type of the FireFly transaction FFEnum: id The UUID of the FireFly transaction UUID"},{"location":"reference/types/tokenpool/","title":"TokenPool","text":"

Token pools are a FireFly construct for describing a set of tokens.

The total supply of a particular fungible token, or a group of related non-fungible tokens.

The exact definition of a token pool is dependent on the token connector implementation.

Check the documentation for your chosen connector implementation to see the detailed options for configuring a new Token Pool.

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.

"},{"location":"reference/types/tokenpool/#example-token-pool-types","title":"Example token pool types","text":"

Some examples of how the generic concept of a Token Pool maps to various well-defined Ethereum standards:

  • ERC-1155: a single contract instance can efficiently allocate many isolated pools of fungible or non-fungible tokens
  • ERC-20 / ERC-777: each contract instance represents a single fungible pool of value, e.g. \"a coin\"
  • ERC-721: each contract instance represents a single pool of NFTs, each with unique identities within the pool
  • ERC-1400 / ERC-1410: partially supported in the same manner as ERC-20/ERC-777, but would require new features for working with partitions

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.

"},{"location":"reference/types/tokenpool/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/tokenpool/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID of the token pool UUID type The type of token the pool contains, such as fungible/non-fungible FFEnum:\"fungible\"\"nonfungible\" namespace The namespace for the token pool string name The name of the token pool. Note the name is not validated against the description of the token on the blockchain string networkName The published name of the token pool within the multiparty network string standard The ERC standard the token pool conforms to, as reported by the token connector string locator A unique identifier for the pool, as provided by the token connector string key 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 string symbol The token symbol. If supplied on input for an existing on-chain token, this must match the on-chain information string decimals Number of decimal places that this token has int connector 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 string message The UUID of the broadcast message used to inform the network about this pool UUID active Indicates whether the pool has been successfully activated with the token connector bool created The creation time of the pool FFTime config 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 JSONObject info Token connector specific information about the pool. See your chosen token connector documentation for details JSONObject tx Reference to the FireFly transaction used to create and broadcast this pool to the network TransactionRef interface A reference to an existing FFI, containing pre-registered type information for the token contract FFIReference interfaceFormat The interface encoding format supported by the connector for this token pool FFEnum:\"abi\"\"ffi\" methods The method definitions resolved by the token connector to be used by each token operation JSONAny published Indicates if the token pool is published to other members of the multiparty network bool"},{"location":"reference/types/tokenpool/#transactionref","title":"TransactionRef","text":"Field Name Description Type type The type of the FireFly transaction FFEnum: id The UUID of the FireFly transaction UUID"},{"location":"reference/types/tokenpool/#ffireference","title":"FFIReference","text":"Field Name Description Type id The UUID of the FireFly interface UUID name The name of the FireFly interface string version The version of the FireFly interface string"},{"location":"reference/types/tokentransfer/","title":"TokenTransfer","text":"

A Token Transfer is created for each transfer of value that happens under a token pool.

The transfers form an off-chain audit history (an \"index\") of the transactions that have been performed on the blockchain.

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.

Hyperledger FireFly maintains this index automatically for all Token Pools that are configured.

"},{"location":"reference/types/tokentransfer/#firefly-initiated-vs-non-firefly-initiated-transfers","title":"FireFly initiated vs. non-FireFly initiated transfers","text":"

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.

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.

"},{"location":"reference/types/tokentransfer/#message-coordinated-transfers","title":"Message coordinated transfers","text":"

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.

These transfers have a message associated with them, and require a compatible Token Connector and on-chain Smart Contract that allows a data payload to be included as part of the transfer, and to be emitted as part of the transfer event.

Examples of how to do this are included in the ERC-20, ERC-721 and ERC-1155 Token Connector sample smart contracts.

"},{"location":"reference/types/tokentransfer/#transfer-types","title":"Transfer types","text":"

There are three primary types of transfer:

  1. Mint - new tokens come into existence, increasing the total supply of tokens within the pool. The from address will be unset for these transfer types.
  2. Burn - existing tokens are taken out of circulation. The to address will be unset for these transfer types.
  3. Transfer - tokens move from ownership by one account, to another account. The from and to addresses are both set for these type of transfers.

Note that the key that signed the Transfer transaction might be different to the from account that is the owner of the tokens before the transfer.

The Approval resource is used to track which signing accounts (other than the owner) have approval to transfer tokens on the owner's behalf.

"},{"location":"reference/types/tokentransfer/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/tokentransfer/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type type The type of transfer such as mint/burn/transfer FFEnum:\"mint\"\"burn\"\"transfer\" localId The UUID of this token transfer, in the local FireFly node UUID pool The UUID the token pool this transfer applies to UUID tokenIndex The index of the token within the pool that this transfer applies to string uri The URI of the token this transfer applies to string connector 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 string namespace The namespace for the transfer, which must match the namespace of the token pool string key The blockchain signing key for the transfer. On input defaults to the first signing key of the organization that operates the node string from The source account for the transfer. On input defaults to the value of 'key' string to The target account for the transfer. On input defaults to the value of 'key' string amount 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 FFBigInt protocolId An alphanumerically sortable string that represents this event uniquely with respect to the blockchain string message The UUID of a message that has been correlated with this transfer using the data field of the transfer in a compatible token connector UUID messageHash The hash of a message that has been correlated with this transfer using the data field of the transfer in a compatible token connector Bytes32 created The creation time of the transfer FFTime tx If submitted via FireFly, this will reference the UUID of the FireFly transaction (if the token connector in use supports attaching data) TransactionRef blockchainEvent The UUID of the blockchain event UUID config Input only field, with token connector specific configuration of the transfer. See your chosen token connector documentation for details JSONObject"},{"location":"reference/types/tokentransfer/#transactionref","title":"TransactionRef","text":"Field Name Description Type type The type of the FireFly transaction FFEnum: id The UUID of the FireFly transaction UUID"},{"location":"reference/types/transaction/","title":"Transaction","text":"

FireFly Transactions are a grouping construct for a number of Operations and Events that need to complete or fail as unit.

FireFly Transactions are not themselves Blockchain transactions, but in many cases there is exactly one Blockchain transaction associated with each FireFly transaction. Exceptions include unpinned transactions, where there is no blockchain transaction at all.

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.

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.

So there is a Blockchain ID 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 Blockchain Event Received event for the detection of the event from the blockchain smart contract when the transaction was mined, and a Message Confirmed event for each message in the batch (in this case 1). Then here the message was a special Definition message that advertised a new Contract API to all members of the network - so there is a Contract API Confirmed event as well.

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.

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.

"},{"location":"reference/types/transaction/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/transaction/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type id The UUID of the FireFly transaction UUID namespace The namespace of the FireFly transaction string type The type of the FireFly transaction FFEnum:\"none\"\"unpinned\"\"batch_pin\"\"network_action\"\"token_pool\"\"token_transfer\"\"contract_deploy\"\"contract_invoke\"\"contract_invoke_pin\"\"token_approval\"\"data_publish\" created 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 FFTime idempotencyKey An optional unique identifier for a transaction. Cannot be duplicated within a namespace, thus allowing idempotent submission of transactions to the API IdempotencyKey blockchainIds 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 string[]"},{"location":"reference/types/verifier/","title":"Verifier","text":"

A verifier is a cryptographic verification mechanism for an identity in FireFly.

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.

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.

  • Ethereum blockchains: The Ethereum address hex string
  • Hyperledger Fabric: The fully qualified MSP Identifier string
  • Data exchange: The data exchange \"Peer ID\", as determined by the DX plugin
"},{"location":"reference/types/verifier/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/verifier/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type hash Hash used as a globally consistent identifier for this namespace + type + value combination on every node in the network Bytes32 identity The UUID of the parent identity that has claimed this verifier UUID namespace The namespace of the verifier string type The type of the verifier FFEnum:\"ethereum_address\"\"tezos_address\"\"fabric_msp_id\"\"dx_peer_id\" value The verifier string, such as an Ethereum address, or Fabric MSP identifier string created The time this verifier was created on this node FFTime"},{"location":"reference/types/wsack/","title":"WSAck","text":"

An ack must be sent on a WebSocket for each event delivered to an application.

Unless autoack is set in the WSStart payload/URL parameters to cause automatic acknowledgement.

Your application should specify the id of each event that it acknowledges.

If the id is omitted, then FireFly will assume the oldest message delivered to the application that has not been acknowledged is the one the ack is associated with.

If multiple subscriptions are started on a WebSocket, then you need to specify the subscription namespace+name as part of each ack.

If you send an acknowledgement that cannot be correlated, then a WSError payload will be sent to the application.

"},{"location":"reference/types/wsack/#example","title":"Example","text":"
{\n    \"type\": \"ack\",\n    \"id\": \"f78bf82b-1292-4c86-8a08-e53d855f1a64\",\n    \"subscription\": {\n        \"namespace\": \"ns1\",\n        \"name\": \"app1_subscription\"\n    }\n}\n
"},{"location":"reference/types/wsack/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type type WSActionBase.type FFEnum:\"start\"\"ack\"\"protocol_error\"\"event_batch\" id WSAck.id UUID subscription WSAck.subscription SubscriptionRef"},{"location":"reference/types/wsack/#subscriptionref","title":"SubscriptionRef","text":"Field Name Description Type id The UUID of the subscription UUID namespace The namespace of the subscription. A subscription will only receive events generated in the namespace of the subscription string name 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 string"},{"location":"reference/types/wserror/","title":"WSError","text":""},{"location":"reference/types/wserror/#example","title":"Example","text":"
{\n    \"type\": \"protocol_error\",\n    \"error\": \"FF10175: Acknowledgment does not match an inflight event + subscription\"\n}\n
"},{"location":"reference/types/wserror/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type type WSAck.type FFEnum:\"start\"\"ack\"\"protocol_error\"\"event_batch\" error WSAck.error string"},{"location":"reference/types/wsstart/","title":"WSStart","text":"

The start payload is sent after an application connects to a WebSocket, to start delivery of events over that connection.

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.

Alternatively the start command can request \"ephemeral\": true in order to dynamically create a new subscription that lasts only for the duration that the connection is active.

"},{"location":"reference/types/wsstart/#example","title":"Example","text":"
{\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
"},{"location":"reference/types/wsstart/#field-descriptions","title":"Field Descriptions","text":"Field Name Description Type type WSActionBase.type FFEnum:\"start\"\"ack\"\"protocol_error\"\"event_batch\" autoack WSStart.autoack bool namespace WSStart.namespace string name WSStart.name string ephemeral WSStart.ephemeral bool filter WSStart.filter SubscriptionFilter options WSStart.options SubscriptionOptions"},{"location":"reference/types/wsstart/#subscriptionfilter","title":"SubscriptionFilter","text":"Field Name Description Type events Regular expression to apply to the event type, to subscribe to a subset of event types string message Filters specific to message events. If an event is not a message event, these filters are ignored MessageFilter transaction Filters specific to events with a transaction. If an event is not associated with a transaction, this filter is ignored TransactionFilter blockchainevent Filters specific to blockchain events. If an event is not a blockchain event, these filters are ignored BlockchainEventFilter topic 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 string topics Deprecated: Please use 'topic' instead string tag Deprecated: Please use 'message.tag' instead string group Deprecated: Please use 'message.group' instead string author Deprecated: Please use 'message.author' instead string"},{"location":"reference/types/wsstart/#messagefilter","title":"MessageFilter","text":"Field Name Description Type tag Regular expression to apply to the message 'header.tag' field string group Regular expression to apply to the message 'header.group' field string author Regular expression to apply to the message 'header.author' field string"},{"location":"reference/types/wsstart/#transactionfilter","title":"TransactionFilter","text":"Field Name Description Type type Regular expression to apply to the transaction 'type' field string"},{"location":"reference/types/wsstart/#blockchaineventfilter","title":"BlockchainEventFilter","text":"Field Name Description Type name Regular expression to apply to the blockchain event 'name' field, which is the name of the event in the underlying blockchain smart contract string listener 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 string"},{"location":"reference/types/wsstart/#subscriptionoptions","title":"SubscriptionOptions","text":"Field Name Description Type firstEvent 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' SubOptsFirstEvent readAhead 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 uint16 withData 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. bool batch 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. bool batchTimeout When batching is enabled, the optional timeout to send events even when the batch hasn't filled. string fastack Webhooks only: When true the event will be acknowledged before the webhook is invoked, allowing parallel invocations bool url Webhooks only: HTTP url to invoke. Can be relative if a base URL is set in the webhook plugin config string method Webhooks only: HTTP method to invoke. Default=POST string json Webhooks only: Whether to assume the response body is JSON, regardless of the returned Content-Type bool reply Webhooks only: Whether to automatically send a reply event, using the body returned by the webhook bool replytag Webhooks only: The tag to set on the reply message string replytx Webhooks only: The transaction type to set on the reply message string headers Webhooks only: Static headers to set on the webhook request `` query Webhooks only: Static query params to set on the webhook request `` tlsConfigName The name of an existing TLS configuration associated to the namespace to use string input Webhooks only: A set of options to extract data from the first JSON input data in the incoming message. Only applies if withData=true WebhookInputOptions retry Webhooks only: a set of options for retrying the webhook call WebhookRetryOptions httpOptions Webhooks only: a set of options for HTTP WebhookHTTPOptions"},{"location":"reference/types/wsstart/#webhookinputoptions","title":"WebhookInputOptions","text":"Field Name Description Type query A top-level property of the first data input, to use for query parameters string headers A top-level property of the first data input, to use for headers string body A top-level property of the first data input, to use for the request body. Default is the whole first body string path A top-level property of the first data input, to use for a path to append with escaping to the webhook path string replytx A top-level property of the first data input, to use to dynamically set whether to pin the response (so the requester can choose) string"},{"location":"reference/types/wsstart/#webhookretryoptions","title":"WebhookRetryOptions","text":"Field Name Description Type enabled Enables retry on HTTP calls, defaults to false bool count Number of times to retry the webhook call in case of failure int initialDelay Initial delay between retries when we retry the webhook call string maxDelay Max delay between retries when we retry the webhookcall string"},{"location":"reference/types/wsstart/#webhookhttpoptions","title":"WebhookHTTPOptions","text":"Field Name Description Type proxyURL HTTP proxy URL to use for outbound requests to the webhook string tlsHandshakeTimeout The max duration to hold a TLS handshake alive string requestTimeout The max duration to hold a TLS handshake alive string maxIdleConns The max number of idle connections to hold pooled int idleTimeout The max duration to hold a HTTP keepalive connection between calls string connectionTimeout The maximum amount of time that a connection is allowed to remain with no data transmitted. string expectContinueTimeout See ExpectContinueTimeout in the Go docs string"},{"location":"releasenotes/","title":"Release Notes","text":"

Full release notes

"},{"location":"releasenotes/#v131-aug-5-2024","title":"v1.3.1 - Aug 5, 2024","text":"

What's New:

  • Enable contract listeners with multiple filters See Contract Listeners for details
  • New multiparty status API at /status/multiparty
"},{"location":"releasenotes/#v130-april-25-2024","title":"v1.3.0 - April 25, 2024","text":"

Migration guide

What's New:

  • Enhancements to FireFly Messaging capabilities, allowing off-chain data to be linked to on-chain transactions from custom smart contracts
  • Sample contract implementation for custom pin contracts
  • Contract interfaces, contract APIs, and token pools can now be separately defined and published
  • Support for batching events when delivering over websockets
  • Lots of bug fixes and miscellaneous enhancements
"},{"location":"releasenotes/#v120-february-6-2023","title":"v1.2.0 - February 6, 2023","text":"

Migration guide

What's New:

  • Enhanced support for token contracts generated by the OpenZeppelin Wizard
  • Custom smart contract error types are now returned on the API
  • Data objects and associated blobs can now be deleted
  • Optional dynamic reload of core configuration file
  • The X-FireFly-Request-ID HTTP header is now passed through to FireFly dependency microservices
  • Custom HTTP headers can be passed through to FireFly dependency microservices
  • Evmconnect is now the default blockchain connector for Ethereum based FireFly stacks
"},{"location":"releasenotes/#release-notes","title":"Release Notes","text":"

Full release notes

"},{"location":"releasenotes/#v110-september-12-2022","title":"v1.1.0 - September 12, 2022","text":"

Migration guide

What's New:

  • Gateway Mode: Connect to many chains with auto-indexing of activities
  • Public EVM Chain Support: Manage public chain connections including Ethereum, Polygon, Arbitrum, Binance Smart Chain, Moonbeam, and more.
  • Namespaces: Isolated environments within a FireFly runtime allowing independent configuration of plugin and infrastructure components and more
  • Connector Toolkit: Quickly build custom connectors
  • Pluggable API Security: Plug in your own API security
  • Mass Scale Tokens: Support many parallel copies of token plugins for mass scale
"},{"location":"releasenotes/#v103-july-07-2022","title":"v1.0.3 - July 07, 2022","text":"

What's New:

  • Adds support for custom URIs for non-fungible tokens and documentation updates
  • Deprecate default value for \"ffdx\"
  • Back port of custom URI support for non-fungible tokens
  • Update token connector versions
  • Back port of \"FAQ and FireFly Tutorial updates\"
"},{"location":"releasenotes/#v102-may-12-2022","title":"v1.0.2 - May 12, 2022","text":"

What's New:

  • Fix invocations on custom Fabric chaincode, which were not properly reporting success/failure status back to FireFly (along with other minor bugfixes).
  • De-duplicate existing token approvals in database migration
  • Backport docs generation and versioning code for 1.0 stream
  • Default fabconnect calls to async
  • Set message header type of broadcast/private
"},{"location":"releasenotes/#v101-may-09-2022","title":"v1.0.1 - May 09, 2022","text":"

What's New:

  • Fixes for token approvals - previously approvals would intermittently be missed by FireFly or recorded with incorrect details.
  • 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.
"},{"location":"releasenotes/#v100-april-28-2022","title":"v1.0.0 - April 28, 2022","text":"

This release includes lots of major hardening, performance improvements, and bug fixes, as well as more complete documentation and OpenAPI specifications.

What's New:

  • Massive performance improvements across the board
  • Up-to-date documentation and fully annotated OpenAPI specification
  • Overhaul of UI
  • Cleaner logs and error messages
  • Lots of bug fixes and miscellaneous enhancements
"},{"location":"releasenotes/#v0140-march-22-2022","title":"v0.14.0 - March 22, 2022","text":"

What's New:

  • Major UI updates including Activity, Blockchain, Off-Chain, Tokens, Network Map, and My Node sections
  • Custom contract APIs
  • Enhanced subscription filters
  • Event API enrichment
  • Performance updates
  • Bug fixes
"},{"location":"releasenotes/#v0130-february-14-2022","title":"v0.13.0 - February 14, 2022","text":"

What's New:

  • Hardening release with significant rework to core of FireFly, mostly to fix issues exposed by the performance testing.
  • Support for running on ARM-based M1 processors
  • Rewrite of the message batching and event aggregation logic inside FireFly, to fix numerous edge cases with lost or hung messages
  • Hardening of operations and transactions to behave more consistently across all types
  • Metrics reporting to Prometheus
  • Continued development to support custom on-chain logic (still in preview)
"},{"location":"releasenotes/#v0120-february-02-2022","title":"v0.12.0 - February 02, 2022","text":"

What's New:

  • All APIs deprecated in v0.11.0 or earlier are removed
  • Preview of custom on-chain logic
  • Support for new ERC20 / ERC721 connector
  • Overhaul of Transaction type and new BlockchainEvent type
  • Support for delivery confirmations via DX plugin
"},{"location":"releasenotes/#v0110-november-22-2021","title":"v0.11.0 - November 22, 2021","text":"

What's New:

  • Significant hardening and enhanced token functionality
  • Major web UI overhaul
  • Optimized database operations for increased transactional throughput
  • Fixed PostgreSQL database migrations
"},{"location":"releasenotes/1.1_migration_guide/","title":"v1.1.0 Migration Guide","text":""},{"location":"releasenotes/1.1_migration_guide/#overview","title":"Overview","text":"

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

If seamless data preservation is not required, you can simply create a new network from scratch using FireFly v1.1.0.

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.

"},{"location":"releasenotes/1.1_migration_guide/#before-upgrading","title":"Before Upgrading","text":"

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.

"},{"location":"releasenotes/1.1_migration_guide/#common-steps","title":"Common Steps","text":"

Upgrade to latest v1.0.x patch release

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.

Fix any deprecated config usage

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.

You can utilize the ffconfig tool to automatically check and fix deprecated config with a command such as:

ffconfig migrate -f <input-file> -o <output-file> --to 1.0.4\n

This should ensure your config file is acceptable to 1.0.x or 1.1.x.

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.

"},{"location":"releasenotes/1.1_migration_guide/#less-common-situations","title":"Less Common Situations","text":"

Record all broadcast namespaces in the config file

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

Identify queries for organization/node identities

Expand for migration details only if your application queries /network/organizations or /network/nodes. 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.

Identify usage of changed APIs

Expand for migration details on all changes to /namespaces, /status, and /network 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. 
/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
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. 
/network/identities - replaced by existing /namespaces/{ns}/identities\n/network/identities/{did} - replaced by new /namespaces/{ns}/identities/{did}\n
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. 
/status/pins - moved to /namespaces/{ns}/pins (or /pins to query the default namespace)\n/status/websockets - moved to /websockets\n
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. 
/namespaces - removed all fields except \"name\", \"description\", \"created\"\n/namespaces/{ns} - same as above\n/namespaces/{ns}/status - removed \"defaults\"\n

Adjust or remove usage of admin APIs

Expand for migration details on all changes to /admin and /spi. 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":"

Backup current data

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.

Upgrade FireFly and all dependencies

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.

"},{"location":"releasenotes/1.1_migration_guide/#after-upgrading","title":"After Upgrading","text":"

Ensure nodes start without errors

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.

Re-broadcast organization and node identities

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 /network/organizations/self and /network/nodes/self (or, if your application uses a non-default namespace, by invoking the /namespace/{ns}-prefixed versions of these APIs).

This will ensure that queries to /network/organizations and /network/nodes 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\").

Update config file to latest format

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.

You can utilize the ffconfig tool to automatically check and fix deprecated config with a command such as:

ffconfig migrate -f <input-file> -o <output-file>\n
"},{"location":"releasenotes/1.1_migration_guide/#upgrading-the-multi-party-contract","title":"Upgrading the Multi-Party Contract","text":"

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.

After upgrading FireFly itself, it is recommended to upgrade your multi-party system to the latest contract version by following these steps.

  1. Compile and deploy an instance of the new FireFly contract (linked above) to your blockchain, using ff deploy or a similar method.
  2. Edit the config file on each node in your network, to add the new contract to the multi-party contract list like so:
namespaces:\n  predefined:\n  - name: default\n    multiparty:\n      enabled: true\n      contract:\n      - location:\n          address: 0x09f107d670b2e69a700a4d9ef1687490ae1568db\n      - location:\n          address: 0x1bee32b37dc48e99c6b6bf037982eb3bee0e816b\n

This example assumes 0x09f1... represents the address of the original contract, and 0x1bee... 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).

  1. After updating each node's configuration, restart the node and ensure it starts without issues.
  2. Have any member of the multi-party network invoke the /namespaces/{ns}/network/action FireFly API with a body of {\"type\": \"terminate\"}. This will terminate the old contract and instruct all members to move simultaneously to the newly configured one.
  3. Verify success by querying /namespaces/{ns}/status on each node and checking that the active multi-party contract matches the new address.
"},{"location":"releasenotes/1.2_migration_guide/","title":"v1.2.0 Migration Guide","text":""},{"location":"releasenotes/1.2_migration_guide/#overview","title":"Overview","text":"

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.

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.

"},{"location":"releasenotes/1.2_migration_guide/#tokens-considerations","title":"Tokens considerations","text":"

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.

"},{"location":"releasenotes/1.2_migration_guide/#sample-token-contract-deprecations","title":"Sample token contract deprecations","text":"

In FireFly v1.2.0 two of the old, lesser used sample token contracts have been deprecated. The ERC20NoData and ERC721NoData contracts have been updated and the previous versions are no longer supported, unless you set the USE_LEGACY_ERC20_SAMPLE=true or USE_LEGACY_ERC721_SAMPLE=true environment variables for your token connector.

For more details you can read the description of the pull requests (#104 and #109) where these changes were made.

"},{"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":"

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.

"},{"location":"releasenotes/1.2_migration_guide/#auto-incrementing-token-index","title":"Auto incrementing token index","text":"

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.

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.

"},{"location":"releasenotes/1.2_migration_guide/#data-management-considerations","title":"Data management considerations","text":"

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.

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.

"},{"location":"releasenotes/1.2_migration_guide/#differences-from-v110_1","title":"Differences from v1.1.0","text":"

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.

NOTE: If data has been published to IPFS, it cannot be deleted completely. You can still call the DELETE method on it, and it will be removed from FireFly's database and Data Exchange, but the payload will still persist in IPFS.

"},{"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":"

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.

"},{"location":"releasenotes/1.2_migration_guide/#transaction-output-details","title":"Transaction output details","text":"

In previous versions of FireFly, transaction output details used to appear under the output 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 fetchStatus=true query parameter when querying for an Operation. Additionally the details have moved from the output field to a new detail 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.

v1.2.0 Operation response body with `fetchStatus=true` 
\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
v1.1.x Operation response body 
\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
"},{"location":"releasenotes/1.2_migration_guide/#local-development-considerations","title":"Local development considerations","text":"

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.

"},{"location":"releasenotes/1.3_migration_guide/","title":"v1.3.0 Migration Guide","text":""},{"location":"releasenotes/1.3_migration_guide/#overview","title":"Overview","text":"

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.

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.

"},{"location":"releasenotes/1.3_migration_guide/#docker-image-file-permission-considerations","title":"Docker image file permission considerations","text":"

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.

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

The new default user is 1001. 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:

  • firefly-evmconnect
  • persistence.leveldb.path directory set in the config file
  • firefly-ethconnect
  • rest.rest-gateway.openapi.storagePath directory in the config file
  • rest.rest-gateway.openapi.eventsDB directory in the config file
  • firefly-fabconnect
  • receipts.leveldb.path directory in the config file
  • events.leveldb.path directory in the config file
  • firefly-dataexchange-https
  • Data directory set by the DATA_DIRECTORY environment variable (default /data)
"},{"location":"releasenotes/1.3_migration_guide/#api-definitionpublication-considerations","title":"API definition/publication considerations","text":"

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.

These following described changes impact contract interfaces, contract APIs, and token pools.

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.

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

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 DELETE APIs to remove the resource.

In FireFly v1.2.0 to create one of the affected resources and publish it to other parties, a POST 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.

"},{"location":"releasenotes/1.3_migration_guide/#contract-interfaces","title":"Contract interfaces","text":"

Previously, to create a contract interface a POST call would be made to /contracts/interfaces and the interface would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the publish=true query parameter, or a subsequent API call can be made on an unpublished interface on POST /contracts/interfaces/{name}/{version}/publish specifying the name and version of the interface.

For an exact view of the changes to contract interfaces, see PR #1279.

"},{"location":"releasenotes/1.3_migration_guide/#contract-apis","title":"Contract APIs","text":"

Previously, to create a contract API a POST call would be made to /apis and the API would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the publish=true query parameter, or a subsequent API call can be made on an unpublished API on /apis/{apiName}/publish specifying the name of the API.

For an exact view of the changes to contract APIs, see PR #1322.

"},{"location":"releasenotes/1.3_migration_guide/#token-pools","title":"Token pools","text":"

Previously, to create a token pool a POST call would be made to /tokens/pools and the token pool would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the publish=true query parameter, or a subsequent API call can be made on an unpublished token pool on /tokens/pools/{nameOrId}/publish specifying the name or ID of the token pool.

For an exact view of the changes to token pools, see PR #1261.

"},{"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":"

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.

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.

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 <plugin_topic_name>/<namespace_name>. For example, an event stream for the default namespace with a plugin topic of 0 would now be: 0/default.

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.

For an exact view of the changes, see PR #1388.

"},{"location":"releasenotes/1.3_migration_guide/#configuration-considerations","title":"Configuration considerations","text":""},{"location":"releasenotes/1.3_migration_guide/#deprecated-configuration","title":"Deprecated configuration","text":"

In FireFly v1.3.0 deprecated configuration options for the blockchain, database, dataexchange, sharedstorage and tokens plugins have been removed, and can no longer be provided.

For an exact view of the changes, see PR #1289.

"},{"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":"

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.

Previously, token pools had a state field with an enumerated value which was either pending, or confirmed, this has been replaced with an active boolean field, where true indicates the token pool has been committed onto chain, and false indicated the transaction has not yet been confirmed.

For an exact view of the changes, see PR #1305.

"},{"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":"

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.

For an exact view of the changes, see PR #1345.

"},{"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":"

FireFly v1.3.0 now uses Go 1.21 across all modules.

"},{"location":"swagger/","title":"API Spec","text":"

This is the FireFly OpenAPI Specification document generated by FireFly

Note: The 'Try it out' buttons will not work on this page because it's not running against a live version of FireFly. To actually try it out, we recommend using the FireFly CLI 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

"},{"location":"tutorials/basic_auth/","title":"Basic Auth","text":""},{"location":"tutorials/basic_auth/#quick-reference","title":"Quick reference","text":"

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:

  1. The main API
  2. The SPI (for internal or admin use)
  3. The metrics API.

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.

FireFly has a basic auth plugin built in, which we will be configuring in this tutorial.

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.

"},{"location":"tutorials/basic_auth/#additional-info","title":"Additional info","text":"
  • Config Reference: HTTP Auth
  • Auth plugin interface
  • Basic auth plugin implementation
"},{"location":"tutorials/basic_auth/#create-a-password-file","title":"Create a password file","text":"

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 htpasswd on a command line to generate a hash file.

"},{"location":"tutorials/basic_auth/#create-the-test_users-password-hash-file","title":"Create the test_users password hash file","text":"
touch test_users\n
"},{"location":"tutorials/basic_auth/#create-a-user-named-firefly","title":"Create a user named firefly","text":"
htpasswd -B test_users firefly\n

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.

htpasswd -B test_users <username>\n
"},{"location":"tutorials/basic_auth/#enable-basic-auth-at-the-namespace-level","title":"Enable basic auth at the Namespace level","text":"

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:

~/.firefly/stacks/<stack_name>/runtime/config/firefly_core_0.yml\n

Open the config file in your favorite editor and add the auth section to the plugins list:

plugins:\n  auth:\n  - name: test_user_auth\n    type: basic\n    basic:\n      passwordfile: /etc/firefly/test_users\n

You will also need to add test_user_auth to the list of plugins used by the default namespace:

namespaces:\n  predefined:\n  - plugins:\n    - database0\n    - blockchain0\n    - dataexchange0\n    - sharedstorage0\n    - erc20_erc721\n    - test_user_auth\n
"},{"location":"tutorials/basic_auth/#mount-the-password-hash-file-in-the-docker-container","title":"Mount the password hash file in the Docker container","text":"

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 docker-compose.override.yml file at:

~/.firefly/stacks/<stack_name>/docker-compose.override.yml\n

Edit the file to look like this, replacing the path to your test_users file:

# 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
"},{"location":"tutorials/basic_auth/#restart-your-firefly-core-container","title":"Restart your FireFly Core container","text":"

To restart your FireFly stack and have Docker pick up the new volume, run:

ff stop <stack_name>\nff start <stack_name>\n

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.

"},{"location":"tutorials/basic_auth/#test-basic-auth","title":"Test basic auth","text":"

After FireFly starts back up, you should be able to test that auth is working correctly by making an unauthenticated request to the API:

curl http://localhost:5000/api/v1/status\n{\"error\":\"FF00169: Unauthorized\"}\n

However, if we add the username and password that we created above, the request should still work:

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
"},{"location":"tutorials/basic_auth/#enable-auth-at-the-http-listener-level","title":"Enable auth at the HTTP listener level","text":"

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:

~/.firefly/stacks/<stack_name>/runtime/config/firefly_core_0.yml\n

Open the config file in your favorite editor and change the spi section to look like the following:

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
"},{"location":"tutorials/basic_auth/#restart-firefly-to-apply-the-changes","title":"Restart FireFly to apply the changes","text":"

NOTE You will need to mount the password hash file following the instructions above if you have not already.

You can run the following to restart your stack:

ff stop <stack_name>\nff start <stack_name>\n
"},{"location":"tutorials/basic_auth/#test-basic-auth_1","title":"Test basic auth","text":"

After FireFly starts back up, you should be able to query the SPI and the request should be unauthorized.

curl http://127.0.0.1:5101/spi/v1/namespaces\n{\"error\":\"FF00169: Unauthorized\"}\n

Adding the username and password that we set earlier, should make the request succeed.

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
"},{"location":"tutorials/broadcast_data/","title":"Broadcast data","text":""},{"location":"tutorials/broadcast_data/#quick-reference","title":"Quick reference","text":"
  • Sends a message visible to all parties in the network
  • The message describes who sent it, and exactly what data was sent
  • A message has one or more attached pieces of business data
  • Can be sent in-line, uploaded in advanced, or received from other parties
  • Can include smaller JSON payloads suitable for database storage
    • These can be verified against a datatype
  • Can include references to large (multi megabyte/gigabyte) Blob data
  • Sequenced via the blockchain
  • The blockchain does not contain any data, just a hash pin
  • Batched for efficiency
  • One batch can pin hundreds of message broadcasts
  • The whole batch is written to the shared storage
"},{"location":"tutorials/broadcast_data/#additional-info","title":"Additional info","text":"
  • Key Concepts: Broadcast / shared data
  • Swagger Reference: POST /api/v1/namespaces/{ns}/messages/broadcast
"},{"location":"tutorials/broadcast_data/#example-1-inline-string-data","title":"Example 1: Inline string data","text":"

POST /api/v1/namespaces/default/messages/broadcast

{\n  \"data\": [\n    {\n      \"value\": \"a string\"\n    }\n  ]\n}\n
"},{"location":"tutorials/broadcast_data/#example-message-response","title":"Example message response","text":"
{\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
"},{"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":"

It is very good practice to set a tag and topic in each of your messages:

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

POST /api/v1/namespaces/default/messages/broadcast

{\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
"},{"location":"tutorials/broadcast_data/#notes-on-why-setting-a-topic-is-important","title":"Notes on why setting a topic is important","text":"

The FireFly aggregator uses the topic (obfuscated on chain) to determine if a message is the next message in an in-flight sequence for any groups the node is involved in. If it is, then that message must receive all off-chain private data and be confirmed before any subsequent messages can be confirmed on the same sequence.

So if you use the same topic in every message, then a single failed send on one topic blocks delivery of all messages between those parties, until the missing data arrives.

Instead it is best practice to set the topic on your messages to a value that identifies an ordered stream of business processing. Some examples:

  • A long-running business process instance identifier assigned at initiation
  • A real-world business transaction identifier used off-chain
  • The agreed identifier of an asset you are attaching a stream of evidence to
  • An NFT identifier that is assigned to an asset (digital twin scenarios)
  • An agreed primary key for a data resource being reconciled between multiple parties

The topic field is an array, because there are cases (such as merging two identifiers) where you need a message to be deterministically ordered across multiple sequences. However, this is an advanced use case and you are likely to set a single topic on the vast majority of your messages.

"},{"location":"tutorials/broadcast_data/#example-3-upload-a-blob-with-metadata-and-broadcast","title":"Example 3: Upload a blob with metadata and broadcast","text":"

Here we make two API calls.

  1. Create the data object explicitly, using a multi-part form upload

  2. You can also just post JSON to this endpoint

  3. Broadcast a message referring to that data

  4. The Blob attachment gets published to shared storage

  5. This happens the first time a broadcast happens on a data attachment
  6. A pin goes to the blockchain
  7. The metadata goes into a batch with the message
"},{"location":"tutorials/broadcast_data/#multipart-form-post-of-a-file","title":"Multipart form post of a file","text":"

Example curl command (Linux/Mac) to grab an image from the internet, and pipe it into a multi-part form post to FireFly.

Note we use autometa to cause FireFly to automatically add the filename, and size, to the JSON part of the data object for us.

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
"},{"location":"tutorials/broadcast_data/#example-data-response-from-blob-upload","title":"Example data response from Blob upload","text":"

Status: 200 OK - your data is uploaded to your local FireFly node

At this point the data has not be shared with anyone else in the network

{\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
"},{"location":"tutorials/broadcast_data/#broadcast-the-uploaded-data","title":"Broadcast the uploaded data","text":"

Just include a reference to the id returned from the upload.

POST /api/v1/namespaces/default/messages/broadcast

{\n  \"data\": [\n    {\n      \"id\": \"97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8\"\n    }\n  ]\n}\n
"},{"location":"tutorials/broadcast_data/#broadcasting-messages-using-the-sandbox","title":"Broadcasting Messages using the Sandbox","text":"

All of the functionality discussed above can be done through the FireFly Sandbox.

To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack.

In the sandbox, enter your message into the message field as seen in the screenshot below.

Notice how the data field in the center panel updates in real time.

Click the blue Run button. This should return a 202 response immediately in the Server Response section and will populate the right hand panel with transaction information after a few seconds.

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

"},{"location":"tutorials/create_custom_identity/","title":"Create a Custom Identity","text":""},{"location":"tutorials/create_custom_identity/#quick-reference","title":"Quick reference","text":"

Out of the box, a FireFly Supernode contains both an org and a node 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.

"},{"location":"tutorials/create_custom_identity/#additional-info","title":"Additional info","text":"
  • Reference: Identities
  • Swagger: POST /api/v1/identities
"},{"location":"tutorials/create_custom_identity/#previous-steps-start-your-environment","title":"Previous steps: Start your environment","text":"

If you haven't started a FireFly stack already, please go to the Getting Started guide on how to Start your environment

\u2190 \u2461 Start your environment

"},{"location":"tutorials/create_custom_identity/#step-1-create-a-new-account","title":"Step 1: Create a new account","text":"

The FireFly CLI has a helpful command to create an account in a local development environment for you.

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.

To create a new account on your local stack, run:

ff accounts create <stack_name>\n
{\n  \"address\": \"0xc00109e112e21165c7065da776c75cfbc9cdc5e7\",\n  \"privateKey\": \"...\"\n}\n

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.

"},{"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":"

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 GET request to the status endpoint on the default namespace.

"},{"location":"tutorials/create_custom_identity/#request","title":"Request","text":"

GET http://localhost:5000/api/v1/status

"},{"location":"tutorials/create_custom_identity/#response","title":"Response","text":"
{\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
"},{"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":"

Now we can POST 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 \"parent\" field in the request.

"},{"location":"tutorials/create_custom_identity/#request_1","title":"Request","text":"

POST http://localhost:5000/api/v1/identities

{\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
"},{"location":"tutorials/create_custom_identity/#response_1","title":"Response","text":"
{\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
"},{"location":"tutorials/create_custom_identity/#step-4-query-the-new-custom-identity","title":"Step 4: Query the New Custom Identity","text":"

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.

"},{"location":"tutorials/create_custom_identity/#request_2","title":"Request","text":"

GET http://localhost:5000/api/v1/identities?fetchverifiers=true

NOTE: Using fetchverifiers=true will return the cryptographic verification mechanism for the FireFly identity.

"},{"location":"tutorials/create_custom_identity/#response_2","title":"Response","text":"
[\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
"},{"location":"tutorials/define_datatype/","title":"Define a datatype","text":""},{"location":"tutorials/define_datatype/#quick-reference","title":"Quick reference","text":"

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.

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.

"},{"location":"tutorials/define_datatype/#additional-info","title":"Additional info","text":"
  • Key Concepts: Broadcast / shared data
  • Swagger: POST /api/v1/namespaces/{ns}/datatypes
"},{"location":"tutorials/define_datatype/#example-1-broadcast-new-datatype","title":"Example 1: Broadcast new datatype","text":"

POST /api/v1/namespaces/{ns}/datatypes

{\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
"},{"location":"tutorials/define_datatype/#example-message-response","title":"Example message response","text":"

Status: 202 Accepted - a broadcast message has been sent, and on confirmation the new datatype will be created (unless it conflicts with another definition with the same name and version that was ordered onto the blockchain before this definition).

{\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
"},{"location":"tutorials/define_datatype/#lookup-the-confirmed-data-type","title":"Lookup the confirmed data type","text":"

GET /api/v1/namespaces/default/datatypes?name=widget&version=0.0.2

[\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
"},{"location":"tutorials/define_datatype/#example-private-send-referring-to-the-datatype","title":"Example private send referring to the datatype","text":"

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 message_rejected event (rather than message_confirmed) for any message that arrives referring to that data.

POST /api/v1/namespaces/default/send/message

{\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
"},{"location":"tutorials/define_datatype/#defining-datatypes-using-the-sandbox","title":"Defining Datatypes using the Sandbox","text":"

You can also define a datatype through the FireFly Sandbox.

To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack.

In the sandbox, enter the datatype's name, version, and JSON Schema as seen in the screenshot below.

{\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

Notice how the data field in the center panel updates in real time.

Click the blue Run button. This should return a 202 response immediately in the Server Response section and will populate the right hand panel with transaction information after a few seconds.

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

"},{"location":"tutorials/events/","title":"Listen for events","text":""},{"location":"tutorials/events/#quick-reference","title":"Quick reference","text":"

Probably the most important aspect of FireFly is that it is an event-driven programming model.

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.

This allows orchestration of complex multi-party system applications and business processes.

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.

The event transports are pluggable. The core transports are WebSockets and Webhooks. We focus on WebSockets in this getting started guide.

Check out the Request/Reply section for more information on Webhooks

"},{"location":"tutorials/events/#additional-info","title":"Additional info","text":"
  • Key Concepts: Multi-party process flow
  • Reference: coming soon
"},{"location":"tutorials/events/#websockets-example-1-ephemeral-subscription-with-auto-commit","title":"WebSockets Example 1: Ephemeral subscription with auto-commit","text":"

The simplest way to get started consuming events, is with an ephemeral WebSocket listener.

Example connection URL:

ws://localhost:5000/ws?namespace=default&ephemeral&autoack&filter.events=message_confirmed

  • namespace=default - event listeners are scoped to a namespace
  • ephemeral - listen for events that occur while this connection is active, but do not remember the app instance (great for UIs)
  • autoack- automatically acknowledge each event, so the next event is sent (great for UIs)
  • filter.events=message_confirmed - only listen for events resulting from a message confirmation

There are a number of browser extensions that let you experiment with WebSockets:

"},{"location":"tutorials/events/#example-event-payload","title":"Example event payload","text":"

The events (by default) do not contain the payload data, just the event and referred message. This means the WebSocket payloads are a predictably small size, and the application can use the information in the message to post-filter the event to decide if it needs to download the full data.

There are server-side filters provided on events as well

{\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
"},{"location":"tutorials/events/#download-the-message-and-data","title":"Download the message and data","text":"

A simple REST API is provided to allow you to download the data associated with the message:

GET /api/v1/namespaces/default/messages/{id}?data=true

"},{"location":"tutorials/events/#download-just-the-data-array-associated-with-a-message","title":"Download just the data array associated with a message","text":"

As you already have the message object in the event delivery, you can query just the array of data objects as follows:

GET /api/v1/namespaces/default/messages/{id}/data

"},{"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":"

To reliably process messages within your application, you should first set up a subscription.

A subscription requests that:

  • FireFly keeps a record of the latest event consumed by that application
  • FireFly only delivers one copy of the event to the application, even when there are multiple active connections

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 id comes from the event it received):

{ \"type\": \"ack\", \"id\": \"617db63-2cf5-4fa3-8320-46150cbb5372\" }\n

You must send an acknowledgement for every message, or you will stop receiving messages.

"},{"location":"tutorials/events/#set-up-the-websocket-subscription","title":"Set up the WebSocket subscription","text":"

Each subscription is scoped to a namespace, and must have a name. You can then choose to perform server-side filtering on the events using regular expressions matched against the information in the event.

POST /namespaces/default/subscriptions

{\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
"},{"location":"tutorials/events/#connect-to-consume-messages","title":"Connect to consume messages","text":"

Example connection URL:

ws://localhost:5000/ws?namespace=default&name=app1

  • namespace=default - event listeners are scoped to a namespace
  • name=app1 - the subscription name
"},{"location":"tutorials/events/#custom-contract-events","title":"Custom Contract Events","text":"

If you are interested in learning more about events for custom smart contracts, please see the Working with custom smart contracts section.

"},{"location":"tutorials/private_send/","title":"Privately send data","text":""},{"location":"tutorials/private_send/#quick-reference","title":"Quick reference","text":"
  • Sends a message to a restricted set of parties
  • The message describes who sent it, to whom, and exactly what data was sent
  • A message has one or more attached pieces of business data
  • Can be sent in-line, uploaded in advanced, or received from other parties
  • Can include smaller JSON payloads suitable for database storage
    • These can be verified against a datatype
  • Can include references to large (multi megabyte/gigabyte) Blob data
  • A group specifies who has visibility to the data
  • The author must be included in the group - auto-added if omitted
  • Can be specified in-line in the message by listing recipients directly
  • Can be referred to by hash
  • Private sends are optionally sequenced via pinning to the blockchain
  • If the send is pinned:
    • The blockchain does not contain any data, just a hash pin
    • Even the ordering context (topic) is obscured in the on-chain data
    • This is true regardless of whether a restricted set of participants are maintaining the ledger, such as in the case of a Fabric Channel.
    • The message should not be considered confirmed (even by the sender) until it has been sequenced via the blockchain and a message_confirmed event occurs
    • Batched for efficiency
    • One batch can pin hundreds of private message sends
    • The batch flows privately off-chain from the sender to each recipient
  • If the send is unpinned:
    • No data is written to the blockchain at all
    • The message is marked confirmed immediately
    • The sender receives a message_confirmed event immediately
    • The other parties in the group get message_confirmed events as soon as the data arrives
"},{"location":"tutorials/private_send/#additional-info","title":"Additional info","text":"
  • Key Concepts: Private data exchange
  • Swagger: POST /api/v1/namespaces/{ns}/messages/private
"},{"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":"

POST /api/v1/namespaces/default/messages/private

{\n  \"data\": [\n    {\n      \"value\": \"a string\"\n    }\n  ],\n  \"group\": {\n    \"members\": [\n      {\n        \"identity\": \"org_1\"\n      }\n    ]\n  }\n}\n
"},{"location":"tutorials/private_send/#example-message-response","title":"Example message response","text":"

Status: 202 Accepted - the message is on it's way, but has not yet been confirmed.

{\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
"},{"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":"

Set header.txtype: \"none\" to disable pinning of the private message send to the blockchain. The message is sent immediately (no batching) over the private data exchange.

POST /api/v1/namespaces/default/messages/private

{\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
"},{"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":"

It is very good practice to set a tag and topic in each of your messages:

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

POST /api/v1/namespaces/default/messages/private

{\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
"},{"location":"tutorials/private_send/#notes-on-why-setting-a-topic-is-important","title":"Notes on why setting a topic is important","text":"

The FireFly aggregator uses the topic (obfuscated on chain) to determine if a message is the next message in an in-flight sequence for any groups the node is involved in. If it is, then that message must receive all off-chain private data and be confirmed before any subsequent messages can be confirmed on the same sequence.

So if you use the same topic in every message, then a single failed send on one topic blocks delivery of all messages between those parties, until the missing data arrives.

Instead it is best practice to set the topic on your messages to value that identifies an ordered stream of business processing. Some examples:

  • A long-running business process instance identifier assigned at initiation
  • A real-world business transaction identifier used off-chain
  • The agreed identifier of an asset you are attaching a stream of evidence to
  • An NFT identifier that is assigned to an asset (digital twin scenarios)
  • An agreed primary key for a data resource being reconciled between multiple parties

The topic field is an array, because there are cases (such as merging two identifiers) where you need a message to be deterministically ordered across multiple sequences. However, this is an advanced use case and you are likely to set a single topic on the vast majority of your messages.

"},{"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":"

Here we make two API calls.

  1. Create the data object explicitly, using a multi-part form upload

  2. You can also just post JSON to this endpoint

  3. Privately send a message referring to that data

  4. The Blob is sent privately to each party

  5. A pin goes to the blockchain
  6. The metadata goes into a batch with the message
"},{"location":"tutorials/private_send/#multipart-form-post-of-a-file","title":"Multipart form post of a file","text":"

Example curl command (Linux/Mac) to grab an image from the internet, and pipe it into a multi-part form post to FireFly.

Note we use autometa to cause FireFly to automatically add the filename, and size, to the JSON part of the data object for us.

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
"},{"location":"tutorials/private_send/#example-data-response-from-blob-upload","title":"Example data response from Blob upload","text":"

Status: 200 OK - your data is uploaded to your local FireFly node

At this point the data has not be shared with anyone else in the network

{\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
"},{"location":"tutorials/private_send/#send-the-uploaded-data-privately","title":"Send the uploaded data privately","text":"

Just include a reference to the id returned from the upload.

POST /api/v1/namespaces/default/messages/private

{\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
"},{"location":"tutorials/private_send/#sending-private-messages-using-the-sandbox","title":"Sending Private Messages using the Sandbox","text":"

All of the functionality discussed above can be done through the FireFly Sandbox.

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.

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

Notice how the data field in the center panel updates in real time as you update the message you wish to send.

Click the blue Run button. This should return a 202 response immediately in the Server Response section and will populate the right hand panel with transaction information after a few seconds.

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

"},{"location":"tutorials/query_messages/","title":"Explore messages","text":""},{"location":"tutorials/query_messages/#quick-reference","title":"Quick reference","text":"

The FireFly Explorer is a great way to view the messages sent and received by your node.

Just open /ui on your FireFly node to access it.

This builds on the APIs to query and filter messages, described below

"},{"location":"tutorials/query_messages/#additional-info","title":"Additional info","text":"
  • Reference: API Query Syntax
  • Swagger: GET /api/v1/namespaces/{ns}/messages
"},{"location":"tutorials/query_messages/#example-1-query-confirmed-messages","title":"Example 1: Query confirmed messages","text":"

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.

The order in which you process messages should be determined by absolute order of message_confirmed events - queryable via the events collection, or through event listeners (discussed next in the getting started guide).

That is because messages are ordered by timestamp, which is potentially subject to adjustments of the clock. Whereas events are ordered by the insertion order into the database, and as such changes in the clock do not affect the order.

GET /api/v1/namespaces/{ns}/messages?pending=false&limit=100

"},{"location":"tutorials/query_messages/#example-response","title":"Example response","text":"
[\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
"},{"location":"tutorials/query_messages/#example-2-query-all-messages","title":"Example 2: Query all messages","text":"

The natural sort order the API will return for messages is:

  • Pending messages first
  • In descending created timestamp order
  • Confirmed messages
  • In descending confirmed timestamp order

GET /api/v1/namespaces/{ns}/messages

"},{"location":"tutorials/rotate_dx_certs/","title":"Rotate DX Certs","text":""},{"location":"tutorials/rotate_dx_certs/#quick-reference","title":"Quick reference","text":"

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.

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.

The high level steps to the process (described in detail below) are:

  • Generate new certs and keys
  • Install new certs and keys on each Data Exchange filesystem
  • Remove old certs from the peer-certs directory
  • Restart each Data Exchange process
  • PATCH the node identity using the FireFly API
"},{"location":"tutorials/rotate_dx_certs/#generate-new-certs-and-keys","title":"Generate new certs and keys","text":"

To generate a new cert, we're going to use a self signed certificate generated by openssl. This is how the FireFly CLI generated the original cert that was used when it created your stack.

For the first member of a FireFly stack you run:

openssl req -new -x509 -nodes -days 365 -subj /CN=dataexchange_0/O=member_0 -keyout key.pem -out cert.pem\n

For the second member:

openssl req -new -x509 -nodes -days 365 -subj /CN=dataexchange_1/O=member_1 -keyout key.pem -out cert.pem\n

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.

"},{"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":"

For a dev environment created with the FireFly CLI, the certificate and key will be located in the /data directory on the Data Exchange node's file system. You can use the docker cp command to copy the file to the correct location, then set the file ownership correctly.

docker cp cert.pem dev_dataexchange_0:/data/cert.pem\ndocker exec dev_dataexchange_0 chown root:root /data/cert.pem\n

NOTE: If your environment is not called dev you may need to change the beginning of the container name in the Docker commands listed in this guide.

"},{"location":"tutorials/rotate_dx_certs/#remove-old-certs-from-the-peer-certs-directory","title":"Remove old certs from the peer-certs directory","text":"

To clear out the old certs from the first Data Exchange node run:

docker exec dev_dataexchange_0 sh -c \"rm /data/peer-certs/*.pem\"\n

To clear out the old certs from the second Data Exchange node run:

docker exec dev_dataexchange_1 sh -c \"rm /data/peer-certs/*.pem\"\n
"},{"location":"tutorials/rotate_dx_certs/#restart-each-data-exchange-process","title":"Restart each Data Exchange process","text":"

To restart your Data Exchange processes, run:

docker restart dev_dataexchange_0\n
docker restart dev_dataexchange_1\n
"},{"location":"tutorials/rotate_dx_certs/#patch-the-node-identity-using-the-firefly-api","title":"PATCH the node identity using the FireFly API","text":"

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.

"},{"location":"tutorials/rotate_dx_certs/#request","title":"Request","text":"

GET http://localhost:5000/api/v1/namespaces/default/identities

"},{"location":"tutorials/rotate_dx_certs/#response","title":"Response","text":"

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:

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

Copy the UUID from the id field, and add that to the PATCH request. In this case it is 20da74a2-d4e6-4eaf-8506-e7cd205d8254.

"},{"location":"tutorials/rotate_dx_certs/#request_1","title":"Request","text":"

Now we will send the new certificate to FireFly. Put the contents of your cert.pem file in the cert field.

NOTE: Usually the cert.pem file will contain line breaks which will not be handled correctly by JSON parsers. Be sure to replace those line breaks with \\n so that the cert field is all on one line as shown below.

PATCH http://localhost:5000/api/v1/namespaces/default/identities/20da74a2-d4e6-4eaf-8506-e7cd205d8254

{\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
"},{"location":"tutorials/rotate_dx_certs/#response_1","title":"Response","text":"
{\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

Repeat these requests for the second member/node running on port 5001. After that you should be back up and running with your new certs, and you should be able to send private messages again.

"},{"location":"tutorials/chains/arbitrum/","title":"Arbitrum","text":"

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.

"},{"location":"tutorials/chains/arbitrum/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"

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.

\u2190 \u2460 Install the FireFly CLI

"},{"location":"tutorials/chains/arbitrum/#create-an-evmconnectyml-config-file","title":"Create an evmconnect.yml config file","text":"

In order to connect to the Binance Smart Chain testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called evmconnect.yml with the following contents:

confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n

For more info about confirmations, see Public vs. Permissioned

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

"},{"location":"tutorials/chains/arbitrum/#creating-a-new-stack","title":"Creating a new stack","text":"

To create a local FireFly development stack and connect it to the Arbitrum testnet, we will use command line flags to customize the following settings:

  • Create a new Ethereum based stack named arbitrum with 1 member
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
  • See the Arbitrum docs and select an HTTPS RPC endpoint.
  • Set the chain ID to 421613 (the correct ID for the Binance Smart Chain testnet)
  • Merge the custom config created above with the generated evmconnect config file

To do this, run the following command:

ff init ethereum arbitrum 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url <selected RPC endpoint> \\\n    --chain-id 421613 \\\n    --connector-config ~/Desktop/evmconnect.yml\n
"},{"location":"tutorials/chains/arbitrum/#start-the-stack","title":"Start the stack","text":"

Now you should be able to start your stack by running:

ff start arbitrum\n

After some time it should print out the following:

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
"},{"location":"tutorials/chains/arbitrum/#get-some-aribitrum","title":"Get some Aribitrum","text":"

At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas.

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

ff accounts list arbitrum\n[\n  {\n    \"address\": \"0x225764d1be1f137be23ddfc426b819512b5d0f3e\",\n    \"privateKey\": \"...\"\n  }\n]\n

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.

"},{"location":"tutorials/chains/arbitrum/#confirm-the-transaction-on-bscscan","title":"Confirm the transaction on Bscscan","text":"

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.

"},{"location":"tutorials/chains/arbitrum/#use-the-public-testnet","title":"Use the public testnet","text":"

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.

"},{"location":"tutorials/chains/avalanche/","title":"Aavalanche","text":"

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.

"},{"location":"tutorials/chains/avalanche/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"

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.

\u2190 \u2460 Install the FireFly CLI

"},{"location":"tutorials/chains/avalanche/#create-an-evmconnectyml-config-file","title":"Create an evmconnect.yml config file","text":"

In order to connect to the Avalanche testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called evmconnect.yml with the following contents:

confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n

For more info about confirmations, see Public vs. Permissioned

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

"},{"location":"tutorials/chains/avalanche/#creating-a-new-stack","title":"Creating a new stack","text":"

To create a local FireFly development stack and connect it to the Avalanche Fuji testnet, we will use command line flags to customize the following settings:

  • Create a new Ethereum based stack named avalanche with 1 member
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
  • See the Avalanche docs and select and HTTPS RPC endpoint.
  • Set the chain ID to 43113 (the correct ID for the Avalanche Fuji testnet)
  • Merge the custom config created above with the generated evmconnect config file

To do this, run the following command:

ff init ethereum avalanche 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url <selected RPC endpoint> \\\n    --chain-id 43113 \\\n    --connector-config ~/Desktop/evmconnect.yml\n
"},{"location":"tutorials/chains/avalanche/#start-the-stack","title":"Start the stack","text":"

Now you should be able to start your stack by running:

ff start avalanche\n

After some time it should print out the following:

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
"},{"location":"tutorials/chains/avalanche/#get-some-avax","title":"Get some AVAX","text":"

At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some AVAX, the native token for Avalanche.

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

ff accounts list avalanche\n[\n  {\n    \"address\": \"0x6688e14f719766cc2a5856ccef63b069703d86f7\",\n    \"privateKey\": \"...\"\n  }\n]\n

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.

"},{"location":"tutorials/chains/avalanche/#confirm-the-transaction-on-snowtrace","title":"Confirm the transaction on Snowtrace","text":"

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.

"},{"location":"tutorials/chains/avalanche/#use-the-public-testnet","title":"Use the public testnet","text":"

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.

"},{"location":"tutorials/chains/binance_smart_chain/","title":"Binance Smart Chain","text":"

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.

"},{"location":"tutorials/chains/binance_smart_chain/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"

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.

\u2190 \u2460 Install the FireFly CLI

"},{"location":"tutorials/chains/binance_smart_chain/#create-an-evmconnectyml-config-file","title":"Create an evmconnect.yml config file","text":"

In order to connect to the Binance Smart Chain testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called evmconnect.yml with the following contents:

confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n

For more info about confirmations, see Public vs. Permissioned

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

"},{"location":"tutorials/chains/binance_smart_chain/#creating-a-new-stack","title":"Creating a new stack","text":"

To create a local FireFly development stack and connect it to the Binance Smart Chain testnet, we will use command line flags to customize the following settings:

  • Create a new Ethereum based stack named bsc with 1 member
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
  • See the Binance BscScan docs and select an HTTPS RPC endpoint.
  • Set the chain ID to 97 (the correct ID for the Binance Smart Chain testnet)
  • Merge the custom config created above with the generated evmconnect config file

To do this, run the following command:

ff init ethereum bsc 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url <selected RPC endpoint> \\\n    --chain-id 97 \\\n    --connector-config ~/Desktop/evmconnect.yml\n
"},{"location":"tutorials/chains/binance_smart_chain/#start-the-stack","title":"Start the stack","text":"

Now you should be able to start your stack by running:

ff start bsc\n

After some time it should print out the following:

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
"},{"location":"tutorials/chains/binance_smart_chain/#get-some-bnb","title":"Get some BNB","text":"

At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some BNB, the native token for Binance Smart Chain.

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

ff accounts list bsc\n[\n  {\n    \"address\": \"0x235461d246ab95d367925b4e91bd2755a921fdd8\",\n    \"privateKey\": \"...\"\n  }\n]\n

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.

"},{"location":"tutorials/chains/binance_smart_chain/#confirm-the-transaction-on-bscscan","title":"Confirm the transaction on Bscscan","text":"

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.

"},{"location":"tutorials/chains/binance_smart_chain/#use-the-public-testnet","title":"Use the public testnet","text":"

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.

"},{"location":"tutorials/chains/fabric_test_network/","title":"Work with Fabric-Samples Test Network","text":"

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

"},{"location":"tutorials/chains/fabric_test_network/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"

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.

\u2190 \u2460 Install the FireFly CLI

"},{"location":"tutorials/chains/fabric_test_network/#start-fabric-test-network-with-fabric-ca","title":"Start Fabric Test Network with Fabric CA","text":"

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 mychannel run:

./network.sh up createChannel -ca\n

NOTE: If you already have the Test Network running, you will need to bring it down first, by running: ./network.sh down

"},{"location":"tutorials/chains/fabric_test_network/#deploy-firefly-chaincode","title":"Deploy FireFly Chaincode","text":"

Next we will need to package and deploy the FireFly chaincode to mychannel 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 fabric-samples repo, you can run the following script from your test-network directory:

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.

#!/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
"},{"location":"tutorials/chains/fabric_test_network/#create-ccpyml-documents","title":"Create ccp.yml documents","text":"

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 ccp.yml for each organization. You will need to fill in one line by replacing the string FILL_IN_KEY_NAME_HERE, because the file name of the private key for each user is randomly generated.

"},{"location":"tutorials/chains/fabric_test_network/#organization-1-connection-profile","title":"Organization 1 connection profile","text":"

Create a new file at ~/org1_ccp.yml with the contents below. Replace the string FILL_IN_KEY_NAME_HERE with the filename in your fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore directory.

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
"},{"location":"tutorials/chains/fabric_test_network/#organization-2-connection-profile","title":"Organization 2 connection profile","text":"

Create a new file at ~/org2_ccp.yml with the contents below. Replace the string FILL_IN_KEY_NAME_HERE with the filename in your fabric-samples/test-network/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/keystore directory.

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
"},{"location":"tutorials/chains/fabric_test_network/#create-the-firefly-stack","title":"Create the FireFly stack","text":"

Now we can create a FireFly stack and pass in these files as command line flags.

NOTE: The following command should be run in the test-network directory as it includes a relative path to the organizations directory containing each org's MSP.

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
"},{"location":"tutorials/chains/fabric_test_network/#edit-docker-composeoverrideyml","title":"Edit docker-compose.override.yml","text":"

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 ~/.firefly/stacks/dev/docker-compose.override.yml and set its contents to the following:

# 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
"},{"location":"tutorials/chains/fabric_test_network/#start-firefly-stack","title":"Start FireFly stack","text":"

Now we can start up FireFly!

ff start dev\n

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.

"},{"location":"tutorials/chains/fabric_test_network/#connecting-to-a-remote-fabric-network","title":"Connecting to a remote Fabric Network","text":"

This same guide can be adapted to connect to a remote Fabric network running somewhere else. They key takeaways are:

  • You need the FireFly chaincode deployed on channel in your Fabric network
  • You need to pass the channel and chaincode name when you run ff init
  • You need to provide a connection profile and the correct certs, keys, etc. for each node when you run ff init
  • Your FireFly containers will need to have network access to your Fabric network
"},{"location":"tutorials/chains/fabric_test_network/#troubleshooting","title":"Troubleshooting","text":"

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.

You may see a message something along the lines of:

ERROR: for firefly_core_0  Container \"bc04521372aa\" is unhealthy.\nEncountered errors while bringing up the project.\n

In this case, we need to look at the container logs to get more detail about what happened. To do this, we can run ff start 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:

ff start dev --verbose --no-rollback\n

Then we could run docker logs <container_name> to see the logs for that container.

"},{"location":"tutorials/chains/fabric_test_network/#no-such-host","title":"No such host","text":"
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

If you see something in your logs that looks like the above, there could be a couple issues:

  1. The hostname for one of your Fabric containers could be wrong in the ccp.yml. Check the ccp.yml for that member and make sure the hostnames are correct.
  2. The FireFly container doesn't have networking connectivity to the Fabric containers. Check the docker-compose.override.yml file to make sure you added the fabric_test network as instructed above.
"},{"location":"tutorials/chains/fabric_test_network/#no-such-file-or-directory","title":"No such file or directory","text":"
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

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 ccp.yml file for that particular member. Check your ccp.yml and make sure all the files listed there exist in your organizations directory.

"},{"location":"tutorials/chains/moonbeam/","title":"Moonbeam Testnet","text":"

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.

"},{"location":"tutorials/chains/moonbeam/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"

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.

\u2190 \u2460 Install the FireFly CLI

"},{"location":"tutorials/chains/moonbeam/#create-an-evmconnectyml-config-file","title":"Create an evmconnect.yml config file","text":"

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 evmconnect.yml with the following contents:

confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n

For more info about confirmations, see Public vs. Permissioned

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

"},{"location":"tutorials/chains/moonbeam/#creating-a-new-stack","title":"Creating a new stack","text":"

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:

  • Create a new Ethereum based stack named moonbeam with 1 member
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
  • See the moonbeam docs and select an HTTPS RPC endpoint
  • Set the chain ID to 1287 (the correct ID for the Moonbeam Alpha testnet)
  • Merge the custom config created above with the generated evmconnect config file

To do this, run the following command:

ff init ethereum moonbeam 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url <selected RPC endpoint> \\\n    --chain-id 1287 \\\n    --connector-config ~/Desktop/evmconnect.yml\n
"},{"location":"tutorials/chains/moonbeam/#start-the-stack","title":"Start the stack","text":"

Now you should be able to start your stack by running:

ff start moonbeam\n

After some time it should print out the following:

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
"},{"location":"tutorials/chains/moonbeam/#get-some-dev","title":"Get some DEV","text":"

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.

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

ff accounts list moonbeam\n[\n  {\n    \"address\": \"0x02d42c32a97c894486afbc7b717edff50c70b292\",\n    \"privateKey\": \"...\"\n  }\n]\n

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.

"},{"location":"tutorials/chains/moonbeam/#confirm-the-transaction-on-moonscan","title":"Confirm the transaction on Moonscan","text":"

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.

"},{"location":"tutorials/chains/moonbeam/#use-the-public-testnet","title":"Use the public testnet","text":"

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.

"},{"location":"tutorials/chains/optimism/","title":"Optimism","text":"

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.

"},{"location":"tutorials/chains/optimism/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"

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.

\u2190 \u2460 Install the FireFly CLI

"},{"location":"tutorials/chains/optimism/#create-an-evmconnectyml-config-file","title":"Create an evmconnect.yml config file","text":"

In order to connect to the Optimism testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called evmconnect.yml with the following contents:

confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

"},{"location":"tutorials/chains/optimism/#creating-a-new-stack","title":"Creating a new stack","text":"

To create a local FireFly development stack and connect it to the Optimism testnet, we will use command line flags to customize the following settings:

  • Create a new Ethereum based stack named optimism with 1 member
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
  • See the optimism docs and select an HTTPS RPC endpoint.
  • Set the chain ID to 420 (the correct ID for the Optimism testnet)
  • Merge the custom config created above with the generated evmconnect config file

To do this, run the following command:

ff init ethereum optimism 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url <selected RPC endpoint> \\\n    --chain-id 420 \\\n    --connector-config ~/Desktop/evmconnect.yml\n
"},{"location":"tutorials/chains/optimism/#start-the-stack","title":"Start the stack","text":"

Now you should be able to start your stack by running:

ff start optimism\n

After some time it should print out the following:

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
"},{"location":"tutorials/chains/optimism/#get-some-optimism","title":"Get some Optimism","text":"

At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some OP, the native token for Optimism.

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

ff accounts list optimism\n[\n  {\n    \"address\": \"0x235461d246ab95d367925b4e91bd2755a921fdd8\",\n    \"privateKey\": \"...\"\n  }\n]\n

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.

"},{"location":"tutorials/chains/optimism/#confirm-the-transaction-on-blockcscout","title":"Confirm the transaction on Blockcscout","text":"

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.

"},{"location":"tutorials/chains/optimism/#use-the-public-testnet","title":"Use the public testnet","text":"

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.

"},{"location":"tutorials/chains/polygon_testnet/","title":"Polygon Testnet","text":"

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.

"},{"location":"tutorials/chains/polygon_testnet/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"

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.

\u2190 \u2460 Install the FireFly CLI

"},{"location":"tutorials/chains/polygon_testnet/#create-an-evmconnectyml-config-file","title":"Create an evmconnect.yml config file","text":"

In order to connect to the Polygon testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called evmconnect.yml with the following contents:

confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n

For more info about confirmations, see Public vs. Permissioned

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

"},{"location":"tutorials/chains/polygon_testnet/#creating-a-new-stack","title":"Creating a new stack","text":"

To create a local FireFly development stack and connect it to the Polygon Mumbai testnet, we will use command line flags to customize the following settings:

  • Create a new Ethereum based stack named polygon with 1 member
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
  • See the list of Polygon RPC endpoints and select an HTTPS RPC endpoint.
  • Set the chain ID to 80001 (the correct ID for the Polygon Mumbai testnet)
  • Merge the custom config created above with the generated evmconnect config file

To do this, run the following command:

ff init ethereum polygon 1 \\\n    --multiparty=false \\\n    -n remote-rpc \\\n    --remote-node-url <selected RPC endpoint> \\\n    --chain-id 80001 \\\n    --connector-config ~/Desktop/evmconnect.yml\n
"},{"location":"tutorials/chains/polygon_testnet/#start-the-stack","title":"Start the stack","text":"

Now you should be able to start your stack by running:

ff start polygon\n

After some time it should print out the following:

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
"},{"location":"tutorials/chains/polygon_testnet/#get-some-matic","title":"Get some MATIC","text":"

At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some MATIC, the native token for Polygon.

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

ff accounts list polygon\n[\n  {\n    \"address\": \"0x02d42c32a97c894486afbc7b717edff50c70b292\",\n    \"privateKey\": \"...\"\n  }\n]\n

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.

"},{"location":"tutorials/chains/polygon_testnet/#confirm-the-transaction-on-polygonscan","title":"Confirm the transaction on Polygonscan","text":"

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.

You can also click on the Internal Txns tab from you account page to see the actual transfer of the MATIC from the faucet.

"},{"location":"tutorials/chains/polygon_testnet/#use-the-public-testnet","title":"Use the public testnet","text":"

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.

"},{"location":"tutorials/chains/tezos_testnet/","title":"Tezos Testnet","text":"

This guide will walk you through the steps to create a local FireFly development environment and connect it to the public Tezos Ghostnet testnet.

"},{"location":"tutorials/chains/tezos_testnet/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"

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.

\u2190 \u2460 Install the FireFly CLI

"},{"location":"tutorials/chains/tezos_testnet/#set-up-the-transaction-signing-service","title":"Set up the transaction signing service","text":"

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.

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.

"},{"location":"tutorials/chains/tezos_testnet/#creating-a-new-stack","title":"Creating a new stack","text":"

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:

  • Create a new Tezos based stack named tezos with 1 member
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
  • See the list of Tezos public RPC nodes and select an HTTPS RPC node.

To do this, run the following command:

ff init tezos dev 1 \\\n    --multiparty=false \\\n    --remote-node-url <selected RPC endpoint>\n

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.

"},{"location":"tutorials/chains/tezos_testnet/#start-the-stack","title":"Start the stack","text":"

Now you should be able to start your stack by running:

ff start dev\n

After some time it should print out the following:

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
"},{"location":"tutorials/chains/tezos_testnet/#get-some-xtz","title":"Get some XTZ","text":"

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.

First, you need to get an account address, which was created during signer set up step.\\ To check that, you can run:

ff accounts list dev\n[\n  {\n    \"address\": \"tz1cuFw1E2Mn2bVS8q8d7QoCb6FXC18JivSp\",\n    \"privateKey\": \"...\"\n  }\n]\n

After that, go to Tezos Ghostnet Faucet and paste the address in the form and click the Request button.

"},{"location":"tutorials/chains/tezos_testnet/#confirm-the-transaction-on-tzstats","title":"Confirm the transaction on TzStats","text":"

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.

On the Transfers tab from you account page you will see the actual transfer of the XTZ from the faucet.

"},{"location":"tutorials/chains/tezos_testnet/#use-the-public-testnet","title":"Use the public testnet","text":"

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.

"},{"location":"tutorials/chains/zksync_testnet/","title":"zkSync Testnet","text":"

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.

"},{"location":"tutorials/chains/zksync_testnet/#previous-steps-install-the-firefly-cli","title":"Previous steps: Install the FireFly CLI","text":"

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.

\u2190 \u2460 Install the FireFly CLI

"},{"location":"tutorials/chains/zksync_testnet/#create-an-evmconnectyml-config-file","title":"Create an evmconnect.yml config file","text":"

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 evmconnect.yml with the following contents:

confirmations:\n  required: 4 # choose the number of confirmations you require\npolicyengine.simple:\n  fixedGasPrice: null\n  gasOracle:\n    mode: connector\n

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

"},{"location":"tutorials/chains/zksync_testnet/#creating-a-new-stack","title":"Creating a new stack","text":"

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:

  • Create a new stack named zkSync with 1 member
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
  • Connect to an ethereum network
  • Use the evmconnect blockchain connector
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
  • See the list of providers for zkSync docs. For this tutorial we will use https://zksync2-testnet.zksync.dev
  • Set the chain ID to 280 (the correct ID for the zkSync testnet)
  • Merge the custom config created above with the generated evmconnect config file

To do this, run the following command:

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
"},{"location":"tutorials/chains/zksync_testnet/#start-the-stack","title":"Start the stack","text":"

Now you should be able to start your stack by running:

ff start zksync\n

After some time it should print out the following:

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
"},{"location":"tutorials/chains/zksync_testnet/#get-some-eth","title":"Get some ETH","text":"

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.

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

ff accounts list zkSync\n[\n  {\n    \"address\": \"0x8cf4fd38b2d56a905113d23b5a7131f0269d8611\",\n    \"privateKey\": \"...\"\n  }\n]\n

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.

"},{"location":"tutorials/chains/zksync_testnet/#confirm-the-transaction-on-the-etherscan-explorer","title":"Confirm the transaction on the Etherscan Explorer","text":"

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.

"},{"location":"tutorials/chains/zksync_testnet/#use-the-public-testnet","title":"Use the public testnet","text":"

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.

"},{"location":"tutorials/custom_contracts/","title":"Work with custom smart contracts","text":""},{"location":"tutorials/custom_contracts/#quick-reference","title":"Quick reference","text":"

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.

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.

"},{"location":"tutorials/custom_contracts/#key-concepts","title":"Key concepts","text":"

FireFly defines the following constructs to support custom smart contracts:

  • Contract Interface: 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.

For more details, you can also have a look at the Reference page for the FireFly Interface Format.

For blockchains that offer a DSL describing the smart contract interface, such as Ethereum's ABI (Application Binary Interface), FireFly offers a convenience tool to convert the DSL into the FFI format.

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.

  • HTTP API: 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 /invoke root path to submit transactions, and a /query root path to send query requests to read the state back out.

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 /invoke calls to eth_sendTransaction JSON-RPC requests, while /query calls are translated into eth_call JSON-RPC requests. One the other hand, the Fabric connector translates /invoke 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).

  • Blockchain Event Listener: 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.

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.

  • Event Subscription: While an event listener tells FireFly to keep track of certain events emitted by the blockchain, an event subscription tells FireFly to relay those events to the client application. Each subscriptions represents a stream of events that can be delivered to a listening client with various modes of delivery with at-least-once delivery guarantee.

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.

"},{"location":"tutorials/custom_contracts/#custom-onchain-logic-async-programming-in-firefly","title":"Custom onchain logic async programming in FireFly","text":"

Like the rest of FireFly, custom onchain logic support are implemented with an asynchronous programming model. The key concepts here are:

  • Transactions are submitted to FireFly and an ID is returned. This is the Operation ID.
  • The transaction itself happens asynchronously from the HTTP request that initiated it
  • 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 blockchain_event_received when this happens.

"},{"location":"tutorials/custom_contracts/ethereum/","title":"Work with Ethereum smart contracts","text":"

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.

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.

"},{"location":"tutorials/custom_contracts/ethereum/#example-smart-contract","title":"Example smart contract","text":"

For this tutorial, we will be using a well known, but slightly modified smart contract called SimpleStorage, 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.

Here is the source for this contract:

// 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
"},{"location":"tutorials/custom_contracts/ethereum/#contract-deployment","title":"Contract deployment","text":"

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.

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.

"},{"location":"tutorials/custom_contracts/ethereum/#request","title":"Request","text":"Field Description key The signing key to use to dpeloy the contract. If omitted, the namespaces's default signing key will be used. contract The compiled bytecode for your smart contract. It should be either a hex encded string or Base64. definition The full ABI JSON array from your compiled JSON file. Copy the entire value of the abi field from the [ to the ]. input An ordered list of constructor arguments. Some contracts may not require any (such as this example).

POST http://localhost:5000/api/v1/namespaces/default/contracts/deploy

{\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
"},{"location":"tutorials/custom_contracts/ethereum/#response","title":"Response","text":"
{\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

Here we can see in the response above under the output section that our new contract address is 0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1. This is the address that we will reference in the rest of this guide.

"},{"location":"tutorials/custom_contracts/ethereum/#the-firefly-interface-format","title":"The FireFly Interface Format","text":"

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.

"},{"location":"tutorials/custom_contracts/ethereum/#request_1","title":"Request","text":"

Here we will take the JSON ABI generated by truffle or solc and POST that to FireFly to have it automatically generate the FireFly Interface for us. Copy the abi from the compiled JSON file, and put that inside an input object like the example below:

POST http://localhost:5000/api/v1/namespaces/default/contracts/interfaces/generate

{\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
"},{"location":"tutorials/custom_contracts/ethereum/#response_1","title":"Response","text":"

FireFly generates and returns the the full FireFly Interface for the SimpleStorage contract in the response body:

{\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
"},{"location":"tutorials/custom_contracts/ethereum/#broadcast-the-contract-interface","title":"Broadcast the contract interface","text":"

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.

We will take the output from the previous HTTP response above, fill in the name and version and then POST that to the /contracts/interfaces API endpoint.

"},{"location":"tutorials/custom_contracts/ethereum/#request_2","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/contracts/interfaces?publish=true

NOTE: Without passing the query parameter publish=true 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 /contracts/interfaces/{name}/{version}/publish

{\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
"},{"location":"tutorials/custom_contracts/ethereum/#response_2","title":"Response","text":"
{\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
"},{"location":"tutorials/custom_contracts/ethereum/#create-an-http-api-for-the-contract","title":"Create an HTTP API for the contract","text":"

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.

We need to copy the id field we got in the response from the previous step to the interface.id 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 simple-storage. Lastly, in the location.address field, we're telling FireFly where an instance of the contract is deployed on-chain.

NOTE: The location 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.

"},{"location":"tutorials/custom_contracts/ethereum/#request_3","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/apis?publish=true

NOTE: Without passing the query parameter publish=true 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 /apis/{apiName}/publish

{\n  \"name\": \"simple-storage\",\n  \"interface\": {\n    \"id\": \"8bdd27a5-67c1-4960-8d1e-7aa31b9084d3\"\n  },\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  }\n}\n
"},{"location":"tutorials/custom_contracts/ethereum/#response_3","title":"Response","text":"
{\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
"},{"location":"tutorials/custom_contracts/ethereum/#view-openapi-spec-for-the-contract","title":"View OpenAPI spec for the contract","text":"

You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled ui in your browser, you should see the Swagger UI for your smart contract.

"},{"location":"tutorials/custom_contracts/ethereum/#invoke-the-smart-contract","title":"Invoke the smart contract","text":"

Now that we've got everything set up, it's time to use our smart contract! We're going to make a POST request to the invoke/set endpoint to set the integer value on-chain. Let's set it to the value of 3 right now.

"},{"location":"tutorials/custom_contracts/ethereum/#request_4","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set

{\n  \"input\": {\n    \"newValue\": 3\n  }\n}\n
"},{"location":"tutorials/custom_contracts/ethereum/#response_4","title":"Response","text":"
{\n  \"id\": \"41c67c63-52cf-47ce-8a59-895fe2ffdc86\"\n}\n

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.

"},{"location":"tutorials/custom_contracts/ethereum/#query-the-current-value","title":"Query the current value","text":"

To make a read-only request to the blockchain to check the current value of the stored integer, we can make a POST to the query/get endpoint.

"},{"location":"tutorials/custom_contracts/ethereum/#request_5","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/query/get

{}\n
"},{"location":"tutorials/custom_contracts/ethereum/#response_5","title":"Response","text":"
{\n  \"output\": \"3\"\n}\n

NOTE: Some contracts may have queries that require input parameters. That's why the query endpoint is a POST, rather than a GET 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.

"},{"location":"tutorials/custom_contracts/ethereum/#passing-additional-options-with-a-request","title":"Passing additional options with a request","text":"

Some smart contract functions may accept or require additional options to be passed with the request. For example, a Solidity function might be payable, meaning that a value field must be specified, indicating an amount of ETH to be transferred with the request. Each of your smart contract API's /invoke or /query endpoints support an options object in addition to the input arguments for the function itself.

Here is an example of sending 100 wei with a transaction:

"},{"location":"tutorials/custom_contracts/ethereum/#request_6","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set

{\n  \"input\": {\n    \"newValue\": 3\n  },\n  \"options\": {\n    \"value\": 100\n  }\n}\n
"},{"location":"tutorials/custom_contracts/ethereum/#response_6","title":"Response","text":"
{\n  \"id\": \"41c67c63-52cf-47ce-8a59-895fe2ffdc86\"\n}\n
"},{"location":"tutorials/custom_contracts/ethereum/#create-a-blockchain-event-listener","title":"Create a blockchain event listener","text":"

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.

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 /contracts/listeners endpoint is RESTful so there are POST, GET, and DELETE methods available on it. To create a new listener, we will make a POST request. We are going to tell FireFly to listen to events with name \"Changed\" 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.

"},{"location":"tutorials/custom_contracts/ethereum/#request_7","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/contracts/listeners

{\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
"},{"location":"tutorials/custom_contracts/ethereum/#response_7","title":"Response","text":"
{\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

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.

"},{"location":"tutorials/custom_contracts/ethereum/#querying-listener-status","title":"Querying listener status","text":"

If you are interested in learning about the current state of a listener you have created, you can query with the fetchstatus 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.

"},{"location":"tutorials/custom_contracts/ethereum/#request-response","title":"Request / Response","text":"

GET http://localhost:5000/api/v1/namespaces/default/contracts/listeners/1bfa3b0f-3d90-403e-94a4-af978d8c5b14?fetchstatus

{\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
"},{"location":"tutorials/custom_contracts/ethereum/#subscribe-to-events-from-our-contract","title":"Subscribe to events from our contract","text":"

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 POST to the /subscriptions endpoint.

We will set a friendly name simple-storage to identify the Subscription when we are connecting to it in the next step.

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 (1bfa3b0f-3d90-403e-94a4-af978d8c5b14) and set that as the value of the listener field in the example below:

"},{"location":"tutorials/custom_contracts/ethereum/#request_8","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/subscriptions

{\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
"},{"location":"tutorials/custom_contracts/ethereum/#response_8","title":"Response","text":"
{\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
"},{"location":"tutorials/custom_contracts/ethereum/#receive-custom-smart-contract-events","title":"Receive custom smart contract events","text":"

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

Connect your WebSocket client to ws://localhost:5000/ws.

After connecting the WebSocket client, send a message to tell FireFly to:

  • Start sending events
  • For the Subscription named simple-storage
  • On the default namespace
  • Automatically \"ack\" each event which will let FireFly immediately send the next event when available
{\n  \"type\": \"start\",\n  \"name\": \"simple-storage\",\n  \"namespace\": \"default\",\n  \"autoack\": true\n}\n
"},{"location":"tutorials/custom_contracts/ethereum/#websocket-event","title":"WebSocket event","text":"

After creating the subscription, you should see an event arrive on the connected WebSocket client that looks something like this:

{\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

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 \"firstEvent\" as \"oldest\". 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.

In the event, we can also see the blockchainevent itself, which has an output object. These are the params in our FireFly Interface, and the actual output of the event. Here we can see the value is 3 which is what we set the integer to in our original transaction.

"},{"location":"tutorials/custom_contracts/ethereum/#subscription-offset","title":"Subscription offset","text":"

If you query by the ID of your subscription with the fetchstatus parameter, you can see its current offset.

GET http://localhost:5000/api/v1/namespaces/default/subscriptions/f826269c-65ed-4634-b24c-4f399ec53a32

{\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

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.

"},{"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":"

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.

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:

  • OpenAPI Spec and Swagger UI are not available
  • Each HTTP request to invoke/query the contract will need to include the contract location
  • The contract location will not have been broadcasted to all other members of the network
  • The URL to invoke/query the contract will be different (described below)
"},{"location":"tutorials/custom_contracts/ethereum/#request_9","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/contracts/interfaces/8bdd27a5-67c1-4960-8d1e-7aa31b9084d3/invoke/set

{\n  \"location\": {\n    \"address\": \"0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1\"\n  },\n  \"input\": {\n    \"newValue\": 7\n  }\n}\n
"},{"location":"tutorials/custom_contracts/ethereum/#response_9","title":"Response","text":"
{\n  \"id\": \"f310fa4a-73d8-4777-9f9d-dfa5012a052f\"\n}\n

All of the same invoke, query, and subscribe endpoints are available on the contract interface itself.

"},{"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":"

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.

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.

"},{"location":"tutorials/custom_contracts/ethereum/#request_10","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/contracts/invoke

{\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
"},{"location":"tutorials/custom_contracts/ethereum/#response_10","title":"Response","text":"
{\n  \"id\": \"386d3e23-e4bc-4a9b-bc1f-452f0a8c9ae5\"\n}\n
"},{"location":"tutorials/custom_contracts/fabric/","title":"Work with Hyperledger Fabric chaincodes","text":"

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.

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.

"},{"location":"tutorials/custom_contracts/fabric/#example-smart-contract","title":"Example smart contract","text":"

For this tutorial, we will be using a well known, but slightly modified smart contract called asset_transfer. It's based on the asset-transfer-basic 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 fabric-samples/asset-transfer-basic/chaincode-go/chaincode/smartcontract.go.

Find the following return statement in the function CreateAsset:

    return ctx.GetStub().PutState(id, assetJSON)\n

and replace it with the following, so that an event will be emitted when the transaction is committed to the channel ledger:

  err = ctx.GetStub().PutState(id, assetJSON)\n  if err != nil {\n    return err\n  }\n  return ctx.GetStub().SetEvent(\"AssetCreated\", assetJSON)\n
"},{"location":"tutorials/custom_contracts/fabric/#create-the-chaincode-package","title":"Create the chaincode package","text":"

Use the peer 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.

  ~ 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

The peer command requires an empty core.yaml file to be present in the working directory to perform the packaging. That's what touch core.yaml did above

The resulting asset_transfer.zip archive file will be used in the next step to deploy to the Fabric network used in FireFly.

"},{"location":"tutorials/custom_contracts/fabric/#contract-deployment","title":"Contract deployment","text":"

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.

The FireFly CLI provides a convenient function to deploy a chaincode package to a local FireFly stack.

NOTE: The contract deployment function of the FireFly CLI is a convenience function to speed up local development, and not intended for production applications

~ johndoe$ ff help deploy fabric\nDeploy a packaged chaincode to the Fabric network used by a FireFly stack\n\nUsage:\n  ff deploy fabric <stack_name> <chaincode_package> <channel> <chaincodeName> <version> [flags]\n

Notice the various parameters used by the command ff deploy fabric. We'll tell the FireFly to deploy using the following parameter values, if your stack setup is different, update the command accordingly:

  • stack name: dev
  • channel: firefly (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)
  • chaincode name: asset_transfer (must match the value of the --label parameter when creating the chaincode package)
  • version: 1.0
$ 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
"},{"location":"tutorials/custom_contracts/fabric/#the-firefly-interface-format","title":"The FireFly Interface Format","text":"

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.

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:

  • structured JSON, used here for the list of chaincode function CreateAsset input parameters
  • array of JSON, used here for the chaincode function GetAllAssets output
  • structured JSON, used here for the list of chaincode event AssetCreated properties
{\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
"},{"location":"tutorials/custom_contracts/fabric/#input-parameters","title":"Input parameters","text":"

For the params section of the CreateAsset function, it is critical that the sequence of the properties (id, color, size, owner, value) matches the order of the input parameters in the chaincode's function signature:

func CreateAsset(ctx contractapi.TransactionContextInterface, id string, color string, size int, owner string, appraisedValue int) error\n
"},{"location":"tutorials/custom_contracts/fabric/#return-values","title":"Return values","text":"

FireFly can automatically decode JSON payloads in the return values. That's why the returns section of the GetAllAssets function only needs to specify the type as array of objects, without having to specify the detailed structure of the JSON payload.

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 AppraisedValue is omitted from the output.

"},{"location":"tutorials/custom_contracts/fabric/#event-payloads","title":"Event payloads","text":"

For events, FireFly automatically decodes JSON payloads. If the event payload is not JSON, base64 encoded bytes will be returned instead. For the events section of the FFI, only the name property needs to be specified.

"},{"location":"tutorials/custom_contracts/fabric/#broadcast-the-contract-interface","title":"Broadcast the contract interface","text":"

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.

We will use the FFI JSON constructed above and POST that to the /contracts/interfaces API endpoint.

"},{"location":"tutorials/custom_contracts/fabric/#request","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/contracts/interfaces?publish=true

NOTE: Without passing the query parameter publish=true 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 /contracts/interfaces/{name}/{version}/publish

{\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
"},{"location":"tutorials/custom_contracts/fabric/#response","title":"Response","text":"
{\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

NOTE: We can broadcast this contract interface conveniently with the help of FireFly Sandbox running at http://127.0.0.1:5108

  • Go to the Contracts Section
  • Click on Define a Contract Interface
  • Select FFI - FireFly Interface in the Interface Fromat dropdown
  • Copy the FFI JSON crafted by you into the Schema Field
  • Click on Run
"},{"location":"tutorials/custom_contracts/fabric/#create-an-http-api-for-the-contract","title":"Create an HTTP API for the contract","text":"

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.

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.

We need to copy the id field we got in the response from the previous step to the interface.id 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 asset_transfer. Lastly, in the location field, we're telling FireFly where an instance of the chaincode is deployed on-chain, which is a chaincode named asset_transfer in the channel firefly.

NOTE: The location 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.

"},{"location":"tutorials/custom_contracts/fabric/#request_1","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/apis?publish=true

NOTE: Without passing the query parameter publish=true 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 /apis/{apiName}/publish

{\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
"},{"location":"tutorials/custom_contracts/fabric/#response_1","title":"Response","text":"
{\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

NOTE: We can create this Http API conveniently with the help of FireFly Sandbox running at http://127.0.0.1:5108

  • Go to the Contracts Section
  • Click on Register a Contract API
  • Select the name of your broadcasted FFI in the Contract Interface dropdown
  • In the Name Field, give a name that will be part of the URL for your Http API
  • In the Chaincode Field, give your chaincode name for which you wrote the FFI
  • In the Channel Field, give the channel name where your chaincode is deployed
  • Click on Run
"},{"location":"tutorials/custom_contracts/fabric/#view-openapi-spec-for-the-contract","title":"View OpenAPI spec for the contract","text":"

You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled ui in your browser, you should see the Swagger UI for your chaincode.

"},{"location":"tutorials/custom_contracts/fabric/#invoke-endpoints","title":"/invoke/* endpoints","text":"

The /invoke endpoints in the generated API are for submitting transactions. These endpoints will be mapped to the POST /transactions endpoint of the FabConnect API.

"},{"location":"tutorials/custom_contracts/fabric/#query-endpoints","title":"/query/* endpoints","text":"

The /query endpoints in the generated API, on the other hand, are for sending query requests. These endpoints will be mapped to the POST /query 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.

"},{"location":"tutorials/custom_contracts/fabric/#invoke-the-chaincode","title":"Invoke the chaincode","text":"

Now that we've got everything set up, it's time to use our chaincode! We're going to make a POST request to the invoke/CreateAsset endpoint to create a new asset.

"},{"location":"tutorials/custom_contracts/fabric/#request_2","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/apis/asset_transfer/invoke/CreateAsset

{\n  \"input\": {\n    \"color\": \"blue\",\n    \"id\": \"asset-01\",\n    \"owner\": \"Harry\",\n    \"size\": \"30\",\n    \"value\": \"23400\"\n  }\n}\n
"},{"location":"tutorials/custom_contracts/fabric/#response_2","title":"Response","text":"
{\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

You'll notice that we got an ID back with status Pending, 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.

"},{"location":"tutorials/custom_contracts/fabric/#query-the-current-state","title":"Query the current state","text":"

To make a read-only request to the blockchain to check the current list of assets, we can make a POST to the query/GetAllAssets endpoint.

"},{"location":"tutorials/custom_contracts/fabric/#request_3","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/apis/asset_transfer/query/GetAllAssets

{}\n
"},{"location":"tutorials/custom_contracts/fabric/#response_3","title":"Response","text":"
[\n  {\n    \"AppraisedValue\": 23400,\n    \"Color\": \"blue\",\n    \"ID\": \"asset-01\",\n    \"Owner\": \"Harry\",\n    \"Size\": 30\n  }\n]\n

NOTE: Some chaincodes may have queries that require input parameters. That's why the query endpoint is a POST, rather than a GET 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.

"},{"location":"tutorials/custom_contracts/fabric/#create-a-blockchain-event-listener","title":"Create a blockchain event listener","text":"

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.

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.

The /contracts/listeners endpoint is RESTful so there are POST, GET, and DELETE methods available on it. To create a new listener, we will make a POST request. We are going to tell FireFly to listen to events with name \"AssetCreated\" 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.

"},{"location":"tutorials/custom_contracts/fabric/#request_4","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/contracts/listeners

{\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
"},{"location":"tutorials/custom_contracts/fabric/#response_4","title":"Response","text":"
{\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
"},{"location":"tutorials/custom_contracts/fabric/#subscribe-to-events-from-our-contract","title":"Subscribe to events from our contract","text":"

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 POST to the /subscriptions endpoint.

We will set a friendly name asset_transfer to identify the Subscription when we are connecting to it in the next step.

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 (6e7f5dd8-5a57-4163-a1d2-5654e784dc31) and set that as the value of the listener field in the example below:

"},{"location":"tutorials/custom_contracts/fabric/#request_5","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/subscriptions

{\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
"},{"location":"tutorials/custom_contracts/fabric/#response_5","title":"Response","text":"
{\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
"},{"location":"tutorials/custom_contracts/fabric/#receive-custom-smart-contract-events","title":"Receive custom smart contract events","text":"

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

Connect your WebSocket client to ws://localhost:5000/ws.

After connecting the WebSocket client, send a message to tell FireFly to:

  • Start sending events
  • For the Subscription named asset_transfer
  • On the default namespace
  • Automatically \"ack\" each event which will let FireFly immediately send the next event when available
{\n  \"type\": \"start\",\n  \"name\": \"asset_transfer\",\n  \"namespace\": \"default\",\n  \"autoack\": true\n}\n
"},{"location":"tutorials/custom_contracts/fabric/#websocket-event","title":"WebSocket event","text":"

After creating the subscription, you should see an event arrive on the connected WebSocket client that looks something like this:

{\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

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 \"firstEvent\" as \"oldest\". 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.

In the event, we can also see the blockchainEvent itself, which has an output object. This contains the event payload that was set by the chaincode.

"},{"location":"tutorials/custom_contracts/pinning/","title":"Pin off-chain data to a custom blockchain transaction","text":"

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.

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.

"},{"location":"tutorials/custom_contracts/pinning/#designing-a-compatible-contract","title":"Designing a compatible contract","text":"

In order to allow pinning a FireFly message batch with a custom contract transaction, your contract must meet certain criteria.

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.

Second, this method must emit a BatchPin 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.

"},{"location":"tutorials/custom_contracts/pinning/#ethereum","title":"Ethereum","text":"
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
  • The method in question will receive packed \"batch pin\" data in its last method parameter (in the form of ABI-encoded bytes). The method must invoke the pinBatchData 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.
  • 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 /status API (under multiparty.contract.location 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.
"},{"location":"tutorials/custom_contracts/pinning/#fabric","title":"Fabric","text":"
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
  • The method in question will received packed \"batch pin\" data in its last method parameter (in the form of a JSON-encoded string). The method must unpack this argument into a JSON object.
  • The contract must directly set a BatchPin event in the same format that is used by the FireFly Multiparty Contract.
"},{"location":"tutorials/custom_contracts/pinning/#initializing-firefly","title":"Initializing FireFly","text":"

Once you have a contract designed, you can initialize your environment using the blockchain of your choice.

No special initialization arguments are needed for Ethereum.

If you are using Fabric, you must pass the --custom-pin-support argument when initializing your FireFly stack. This will ensure that the BatchPin 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.

"},{"location":"tutorials/custom_contracts/pinning/#invoking-the-contract","title":"Invoking the contract","text":"

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.

POST http://localhost:5000/api/v1/namespaces/default/apis/custom-pin/invoke/sayHello

{\n  \"input\": {},\n  \"message\": {\n    \"data\": [\n      {\n        \"value\": \"payload here\"\n      }\n    ]\n  }\n}\n
"},{"location":"tutorials/custom_contracts/pinning/#listening-for-events","title":"Listening for events","text":"

All parties that receive the message will receive a message_confirmed 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 message_confirmed 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.

"},{"location":"tutorials/custom_contracts/tezos/","title":"Work with Tezos smart contracts","text":"

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.

"},{"location":"tutorials/custom_contracts/tezos/#smart-contract-languages","title":"Smart Contract Languages","text":"

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.

NOTE: For this tutorial we are going to use SmartPy for building Tezos smart contracts utilizing the broadly adopted Python language.

"},{"location":"tutorials/custom_contracts/tezos/#example-smart-contract","title":"Example smart contract","text":"

First let's look at a simple contract smart contract called SimpleStorage, 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.

NOTE: Smart contract's tests (marked with @sp.add_test annotation) are used to verify the validity of contract entrypoints and do not affect the state of the contract during deployment.

Here is the source for this contract:

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
"},{"location":"tutorials/custom_contracts/tezos/#contract-deployment-via-smartpy-ide","title":"Contract deployment via SmartPy IDE","text":"

To deploy the contract, we will use SmartPy IDE.

  1. Open an IDE;
  2. Paste the contract code;
  3. Click \"Run code\" button;
  4. Then you will see \"Show Michelson\" button, click on that;
  5. On the opened pop-up click button \"Deploy Contract\";
  6. Choose the Ghostnet network;
  7. Select an account, which you're going to use to deploy the contract;
  8. Click \"Estimate Cost From RPC\" button;
  9. Click \"Deploy Contract\" button;

Here we can see that our new contract address is KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg. This is the address that we will reference in the rest of this guide.

"},{"location":"tutorials/custom_contracts/tezos/#contract-deployment-via-http-api","title":"Contract deployment via HTTP API","text":"

To deploy the contract we can use HTTP API: POST http://localhost:5000/api/v1/namespaces/default/contracts/deploy

{\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

The contract field has two fields - code with Michelson code of contract and storage with initial Storage values.

The response of request above:

{\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

The success result of deploy can be checked by GET http://localhost:5000/api/v1/namespaces/default/operations/0c3810c7-baed-4077-9d2c-af316a4a567f where 0c3810c7-baed-4077-9d2c-af316a4a567f is operation id from response above.

The success response:

{\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
"},{"location":"tutorials/custom_contracts/tezos/#the-firefly-interface-format","title":"The FireFly Interface Format","text":"

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.

"},{"location":"tutorials/custom_contracts/tezos/#schema-details","title":"Schema details","text":"

The details field is used to encapsulate blockchain specific type information about a specific field. (More details at schema details)

"},{"location":"tutorials/custom_contracts/tezos/#supported-tezos-types","title":"Supported Tezos types","text":"
  • nat
  • integer
  • string
  • address
  • bytes
  • boolean
  • variant
  • list
  • struct
  • map
"},{"location":"tutorials/custom_contracts/tezos/#internal-type-vs-internal-schema","title":"Internal type vs Internal schema","text":"

internalType is a field which is used to describe tezos primitive types

{\n  \"details\": {\n    \"type\": \"address\",\n    \"internalType\": \"address\"\n  }\n}\n

internalSchema in turn is used to describe more complex tezos types as list, struct or variant

Struct example:

{\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

List example:

{\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

Variant example:

{\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

Map example:

{\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
"},{"location":"tutorials/custom_contracts/tezos/#options","title":"Options","text":"

Option type is used to indicate a value as optional (see more at smartpy options)

{\n  \"details\": {\n    \"type\": \"string\",\n    \"internalType\": \"string\",\n    \"kind\": \"option\"\n  }\n}\n
"},{"location":"tutorials/custom_contracts/tezos/#fa2-example","title":"FA2 example","text":"

The following FFI sample demonstrates the specification for the widely used FA2 (analogue of ERC721 for EVM) smart contract:

{\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
"},{"location":"tutorials/custom_contracts/tezos/#broadcast-the-contract-interface","title":"Broadcast the contract interface","text":"

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.

We will use the FFI JSON constructed above and POST that to the /contracts/interfaces API endpoint.

"},{"location":"tutorials/custom_contracts/tezos/#request","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/contracts/interfaces

{\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
"},{"location":"tutorials/custom_contracts/tezos/#response","title":"Response","text":"
{\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

NOTE: We can broadcast this contract interface conveniently with the help of FireFly Sandbox running at http://127.0.0.1:5108

  • Go to the Contracts Section
  • Click on Define a Contract Interface
  • Select FFI - FireFly Interface in the Interface Fromat dropdown
  • Copy the FFI JSON crafted by you into the Schema Field
  • Click on Run
"},{"location":"tutorials/custom_contracts/tezos/#create-an-http-api-for-the-contract","title":"Create an HTTP API for the contract","text":"

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.

We need to copy the id field we got in the response from the previous step to the interface.id 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 simple-storage. Lastly, in the location.address field, we're telling FireFly where an instance of the contract is deployed on-chain.

NOTE: The location 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.

"},{"location":"tutorials/custom_contracts/tezos/#request_1","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/apis

{\n  \"name\": \"simple-storage\",\n  \"interface\": {\n    \"id\": \"f9e34787-e634-46cd-af47-b52c537404ff\"\n  },\n  \"location\": {\n    \"address\": \"KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg\"\n  }\n}\n
"},{"location":"tutorials/custom_contracts/tezos/#response_1","title":"Response","text":"
{\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
"},{"location":"tutorials/custom_contracts/tezos/#view-openapi-spec-for-the-contract","title":"View OpenAPI spec for the contract","text":"

You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled ui in your browser, you should see the Swagger UI for your smart contract.

"},{"location":"tutorials/custom_contracts/tezos/#invoke-the-smart-contract","title":"Invoke the smart contract","text":"

Now that we've got everything set up, it's time to use our smart contract! We're going to make a POST request to the invoke/set endpoint to set the integer value on-chain. Let's set it to the value of 3 right now.

"},{"location":"tutorials/custom_contracts/tezos/#request_2","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set

{\n  \"input\": {\n    \"newValue\": 3\n  }\n}\n
"},{"location":"tutorials/custom_contracts/tezos/#response_2","title":"Response","text":"
{\n  \"id\": \"87c7ee1b-33d1-46e2-b3f5-8566c14367cf\",\n  \"type\": \"blockchain_invoke\",\n  \"status\": \"Pending\",\n  \"...\"\n}\n

You'll notice that we got an ID back with status Pending, 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.

"},{"location":"tutorials/custom_contracts/tezos/#query-the-current-value","title":"Query the current value","text":"

To make a read-only request to the blockchain to check the current value of the stored integer, we can make a POST to the query/get endpoint.

"},{"location":"tutorials/custom_contracts/tezos/#request_3","title":"Request","text":"

POST http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/query/get

{}\n
"},{"location":"tutorials/custom_contracts/tezos/#response_3","title":"Response","text":"
{\n  \"3\"\n}\n

NOTE: Some contracts may have queries that require input parameters. That's why the query endpoint is a POST, rather than a GET 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.

"},{"location":"tutorials/tokens/","title":"Use tokens","text":""},{"location":"tutorials/tokens/#quick-reference","title":"Quick reference","text":"

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.

  • FireFly provides an abstraction layer for multiple types of tokens
  • Tokens are grouped into pools, which each represent a particular type or class of token
  • Each pool is classified as fungible or non-fungible
  • In the case of non-fungible tokens, the pool is subdivided into individual tokens with a unique token index
  • Within a pool, you may mint (issue), transfer, and burn (redeem) tokens
  • Each operation can be optionally accompanied by a broadcast or private message, which will be recorded alongside the transfer on-chain
  • FireFly tracks a history of all token operations along with all current token balances
  • The blockchain backing each token connector may be the same or different from the one backing FireFly message pinning
"},{"location":"tutorials/tokens/#what-is-a-pool","title":"What is a pool?","text":"

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:

  • ERC-1155: a single contract instance can efficiently allocate many isolated pools of fungible or non-fungible tokens
  • ERC-20 / ERC-777: each contract instance represents a single fungible pool of value, e.g. \"a coin\"
  • ERC-721: each contract instance represents a single pool of NFTs, each with unique identities within the pool
  • ERC-1400 / ERC-1410: partially supported in the same manner as ERC-20/ERC-777, but would require new features for working with partitions

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.

"},{"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":"

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.

\u2190 \u2460 Install the FireFly CLI

"},{"location":"tutorials/tokens/erc1155/#create-a-stack-with-an-erc-1155-connector","title":"Create a stack with an ERC-1155 connector","text":"

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:

ff init ethereum -t erc-1155\n

Then run:

ff start <your_stack_name>\n
"},{"location":"tutorials/tokens/erc1155/#about-the-sample-token-contract","title":"About the sample token contract","text":"

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.

\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":"

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.

"},{"location":"tutorials/tokens/erc1155/#create-a-pool-using-default-token-contract","title":"Create a pool (using default token contract)","text":"

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 name and type (fungible or nonfungible) for the pool.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

NOTE: Without passing the query parameter publish=true 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 /tokens/pools/{nameOrId}/publish

{\n  \"name\": \"testpool\",\n  \"type\": \"fungible\"\n}\n

Other parameters:

  • You must specify a connector if you have configured multiple token connectors
  • You may pass through a config object of additional parameters, if supported by your token connector
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
"},{"location":"tutorials/tokens/erc1155/#create-a-pool-from-a-deployed-token-contract","title":"Create a pool (from a deployed token contract)","text":"

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.

See the README of the token connector for details on what contract variants can currently be understood.

You can pass a config object with an address when you make the request to create the token pool, and if you created a contract interface, you can include the interface ID as well.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

NOTE: Without passing the query parameter publish=true 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 /tokens/pools/{nameOrId}/publish

{\n  \"name\": \"testpool\",\n  \"type\": \"fungible\",\n  \"interface\": {\n    \"id\": \"b9e5e1ce-97bb-4a35-a25c-52c7c3f523d8\"\n  },\n  \"config\": {\n    \"address\": \"0xb1C845D32966c79E23f733742Ed7fCe4B41901FC\"\n  }\n}\n
"},{"location":"tutorials/tokens/erc1155/#mint-tokens","title":"Mint tokens","text":"

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.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint

{\n  \"amount\": 10\n}\n

Other parameters:

  • You must specify a pool name if you've created more than one pool
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
  • You may specify to if you'd like to send the minted tokens to a specific identity (default is the same as key)
"},{"location":"tutorials/tokens/erc1155/#transfer-tokens","title":"Transfer tokens","text":"

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.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

{\n  \"amount\": 1,\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\"\n}\n

NOTE: When transferring a non-fungible token, the amount must always be 1. The tokenIndex field is also required when transferring a non-fungible token.

Other parameters:

  • You must specify a pool name if you've created more than one pool
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
  • You may specify from if you'd like to send tokens from a specific identity (default is the same as key)
"},{"location":"tutorials/tokens/erc1155/#sending-data-with-a-transfer","title":"Sending data with a transfer","text":"

All transfers (as well as mint/burn operations) support an optional message 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.

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.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

"},{"location":"tutorials/tokens/erc1155/#broadcast-message","title":"Broadcast message","text":"
{\n  \"amount\": 1,\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n
"},{"location":"tutorials/tokens/erc1155/#private-message","title":"Private message","text":"
{\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

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.

"},{"location":"tutorials/tokens/erc1155/#burn-tokens","title":"Burn tokens","text":"

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.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn

{\n  \"amount\": 1\n}\n

NOTE: When burning a non-fungible token, the amount must always be 1. The tokenIndex field is also required when burning a non-fungible token.

Other parameters:

  • You must specify a pool name if you've created more than one pool
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
  • You may specify from if you'd like to burn tokens from a specific identity (default is the same as key)
"},{"location":"tutorials/tokens/erc1155/#token-approvals","title":"Token approvals","text":"

You can also approve other wallets to transfer tokens on your behalf with the /approvals API. The important fields in a token approval API request are as follows:

  • approved: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to true. Setting to false can revoke an existing approval.
  • operator: The other account that is allowed to transfer tokens out of the wallet specified in the key field
  • key: The wallet address for the approval. If not set, it defaults to the address of the FireFly node submitting the transaction

Here is an example request that would let the signing account 0x634ee8c7d0894d086c7af1fc8514736aed251528 transfer any amount of tokens from my wallet

"},{"location":"tutorials/tokens/erc1155/#request","title":"Request","text":"

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals

{\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\"\n}\n
"},{"location":"tutorials/tokens/erc1155/#response","title":"Response","text":"
{\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
"},{"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":"

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.

\u2190 \u2461 Start your environment

"},{"location":"tutorials/tokens/erc20/#about-the-sample-token-contracts","title":"About the sample token contracts","text":"

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 type in the API request.

\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":"

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.

"},{"location":"tutorials/tokens/erc20/#create-a-pool-using-default-token-factory","title":"Create a pool (using default token factory)","text":"

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 name and type for the pool.

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.

"},{"location":"tutorials/tokens/erc20/#request","title":"Request","text":"

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

NOTE: Without passing the query parameter publish=true 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 /tokens/pools/{nameOrId}/publish

{\n  \"name\": \"testpool\",\n  \"type\": \"fungible\"\n}\n
"},{"location":"tutorials/tokens/erc20/#response","title":"Response","text":"
{\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

Other parameters:

  • You must specify a connector if you have configured multiple token connectors
  • You may pass through a config object of additional parameters, if supported by your token connector
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
"},{"location":"tutorials/tokens/erc20/#get-the-address-of-the-deployed-contract","title":"Get the address of the deployed contract","text":"

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 GET request to the pool's ID:

"},{"location":"tutorials/tokens/erc20/#request_1","title":"Request","text":"

GET http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools/5811e8d5-52d0-44b1-8b75-73f5ff88f598

"},{"location":"tutorials/tokens/erc20/#response_1","title":"Response","text":"
{\n  \"id\": \"e1477ed5-7282-48e5-ad9d-1612296bb29d\",\n  \"type\": \"fungible\",\n  \"namespace\": \"default\",\n  \"name\": \"testpool\",\n  \"standard\": \"ERC20\",\n  \"locator\": \"address=0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c&schema=ERC20WithData&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
"},{"location":"tutorials/tokens/erc20/#create-a-pool-from-a-deployed-token-contract","title":"Create a pool (from a deployed token contract)","text":"

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.

See the README of the token connector for details on what contract variants can currently be understood.

You can pass a config object with an address and blockNumber when you make the request to create the token pool, and if you created a contract interface, you can include the interface ID as well.

"},{"location":"tutorials/tokens/erc20/#request_2","title":"Request","text":"

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

NOTE: Without passing the query parameter publish=true 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 /tokens/pools/{nameOrId}/publish

{\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
"},{"location":"tutorials/tokens/erc20/#mint-tokens","title":"Mint tokens","text":"

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.

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\u00d71018 = 100000000000000000000. This allows users to work with \"fractional\" tokens even though Ethereum virtual machines only support integer arithmetic.

"},{"location":"tutorials/tokens/erc20/#request_3","title":"Request","text":"

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint

{\n  \"amount\": \"100000000000000000000\"\n}\n
"},{"location":"tutorials/tokens/erc20/#response_2","title":"Response","text":"
{\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

Other parameters:

  • You must specify a pool name if you've created more than one pool
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
  • You may specify to if you'd like to send the minted tokens to a specific identity (default is the same as key)
"},{"location":"tutorials/tokens/erc20/#transfer-tokens","title":"Transfer tokens","text":"

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.

"},{"location":"tutorials/tokens/erc20/#request_4","title":"Request","text":"

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

{\n  \"amount\": \"10000000000000000000\",\n  \"to\": \"0xa4222a4ae19448d43a338e6586edd5fb2ac398e1\"\n}\n
"},{"location":"tutorials/tokens/erc20/#response_3","title":"Response","text":"
{\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

Other parameters:

  • You must specify a pool name if you've created more than one pool
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
  • You may specify from if you'd like to send tokens from a specific identity (default is the same as key)
"},{"location":"tutorials/tokens/erc20/#sending-data-with-a-transfer","title":"Sending data with a transfer","text":"

All transfers (as well as mint/burn operations) support an optional message 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.

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.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

"},{"location":"tutorials/tokens/erc20/#broadcast-message","title":"Broadcast message","text":"
{\n  \"amount\": 1,\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n
"},{"location":"tutorials/tokens/erc20/#private-message","title":"Private message","text":"
{\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

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.

"},{"location":"tutorials/tokens/erc20/#burn-tokens","title":"Burn tokens","text":"

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.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn

{\n  \"amount\": 1\n}\n

Other parameters:

  • You must specify a pool name if you've created more than one pool
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
  • You may specify from if you'd like to burn tokens from a specific identity (default is the same as key)
"},{"location":"tutorials/tokens/erc20/#token-approvals","title":"Token approvals","text":"

You can also approve other wallets to transfer tokens on your behalf with the /approvals API. The important fields in a token approval API request are as follows:

  • approved: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to true. Setting to false can revoke an existing approval.
  • operator: The other account that is allowed to transfer tokens out of the wallet specified in the key field.
  • config.allowance: The number of tokens the other account is allowed to transfer. If 0 or not set, the approval is valid for any number.
  • key: The wallet address for the approval. If not set, it defaults to the address of the FireFly node submitting the transaction.

Here is an example request that would let the signing account 0x634ee8c7d0894d086c7af1fc8514736aed251528 transfer up to 10\u00d71018 (10000000000000000000) tokens from my wallet

"},{"location":"tutorials/tokens/erc20/#request_5","title":"Request","text":"

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals

{\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\",\n  \"config\": {\n    \"allowance\": \"10000000000000000000\"\n  }\n}\n
"},{"location":"tutorials/tokens/erc20/#response_4","title":"Response","text":"
{\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
"},{"location":"tutorials/tokens/erc20/#use-metamask","title":"Use Metamask","text":"

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.

"},{"location":"tutorials/tokens/erc20/#configure-a-new-network","title":"Configure a new network","text":"

The first thing we need to do is tell Metamask how to connect to our local blockchain node. To do that:

  • Click your account icon

  • In the drop down menu, click Settings

  • On the left hand side of the page, click Networks

  • Click the Add a network button

  • Fill in the network details:

  • Network Name: FireFly (could be any name)
  • New RPC URL: http://127.0.0.1:5100
  • Chain ID: 2021
  • Currency Symbol: ETH
  • Click Save
"},{"location":"tutorials/tokens/erc20/#import-tokens","title":"Import tokens","text":"

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.

  • Click on Import tokens

  • Enter the Ethereum address of the contract

  • Enter a Token Symbol (can be anything you want)
  • Click Add Custom Token

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 GET to http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools to lookup your configured token pools.

"},{"location":"tutorials/tokens/erc20/#transfer-tokens_1","title":"Transfer tokens","text":"

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.

After a couple seconds, you should see your tokens show up in your Metamask wallet.

You can also send tokens to a FireFly address or any other Ethereum address from your Metamask wallet.

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.

"},{"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":"

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.

\u2190 \u2461 Start your environment

"},{"location":"tutorials/tokens/erc721/#about-the-sample-token-contracts","title":"About the sample token contracts","text":"

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 type in the API request.

\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":"

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.

"},{"location":"tutorials/tokens/erc721/#create-a-pool-using-default-token-factory","title":"Create a pool (using default token factory)","text":"

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 name and type for the pool.

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.

"},{"location":"tutorials/tokens/erc721/#request","title":"Request","text":"

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

NOTE: Without passing the query parameter publish=true 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 /tokens/pools/{nameOrId}/publish

{\n  \"type\": \"nonfungible\",\n  \"name\": \"nfts\"\n}\n
"},{"location":"tutorials/tokens/erc721/#response","title":"Response","text":"
{\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

Other parameters:

  • You must specify a connector if you have configured multiple token connectors
  • You may pass through a config object of additional parameters, if supported by your token connector
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
"},{"location":"tutorials/tokens/erc721/#get-the-address-of-the-deployed-contract","title":"Get the address of the deployed contract","text":"

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 GET request to the pool's ID:

"},{"location":"tutorials/tokens/erc721/#request_1","title":"Request","text":"

GET http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools/5811e8d5-52d0-44b1-8b75-73f5ff88f598

"},{"location":"tutorials/tokens/erc721/#response_1","title":"Response","text":"
{\n  \"id\": \"a92a0a25-b886-4b43-931f-4add2840258a\",\n  \"type\": \"nonfungible\",\n  \"namespace\": \"default\",\n  \"name\": \"nfts\",\n  \"standard\": \"ERC721\",\n  \"locator\": \"address=0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c&schema=ERC721WithData&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
"},{"location":"tutorials/tokens/erc721/#create-a-pool-from-a-deployed-token-contract","title":"Create a pool (from a deployed token contract)","text":"

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.

See the README of the token connector for details on what contract variants can currently be understood.

You can pass a config object with an address and blockNumber when you make the request to create the token pool, and if you created a contract interface, you can include the interface ID as well.

"},{"location":"tutorials/tokens/erc721/#request_2","title":"Request","text":"

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

NOTE: Without passing the query parameter publish=true 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 /tokens/pools/{nameOrId}/publish

{\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
"},{"location":"tutorials/tokens/erc721/#mint-a-token","title":"Mint a token","text":"

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:

  • only the creator of a pool is allowed to mint within that pool
  • the tokenIndex must be set to a unique value
  • the amount must be 1

A different ERC-721 contract may define its own requirements.

"},{"location":"tutorials/tokens/erc721/#request_3","title":"Request","text":"

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint

{\n  \"amount\": \"1\",\n  \"tokenIndex\": \"1\"\n}\n
"},{"location":"tutorials/tokens/erc721/#response_2","title":"Response","text":"
{\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

Other parameters:

  • You must specify a pool name if you've created more than one pool
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
  • You may specify to if you'd like to send the minted tokens to a specific identity (default is the same as key)
"},{"location":"tutorials/tokens/erc721/#transfer-a-token","title":"Transfer a token","text":"

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.

When transferring an NFT, you must also specify the tokenIndex that you wish to transfer. The tokenIndex is simply the ID of the specific NFT within the pool that you wish to transfer.

NOTE: When transferring NFTs the amount must be 1. If you wish to transfer more NFTs, simply call the endpoint multiple times, specifying the token index of each token to transfer.

"},{"location":"tutorials/tokens/erc721/#request_4","title":"Request","text":"

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

{\n  \"amount\": \"1\",\n  \"tokenIndex\": \"1\",\n  \"to\": \"0xa4222a4ae19448d43a338e6586edd5fb2ac398e1\"\n}\n
"},{"location":"tutorials/tokens/erc721/#response_3","title":"Response","text":"
{\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

Other parameters:

  • You must specify a pool name if you've created more than one pool
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
  • You may specify from if you'd like to send tokens from a specific identity (default is the same as key)
"},{"location":"tutorials/tokens/erc721/#sending-data-with-a-transfer","title":"Sending data with a transfer","text":"

All transfers (as well as mint/burn operations) support an optional message 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.

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.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

"},{"location":"tutorials/tokens/erc721/#broadcast-message","title":"Broadcast message","text":"
{\n  \"amount\": 1,\n  \"tokenIndex\": \"1\",\n  \"to\": \"0x07eab7731db665caf02bc92c286f51dea81f923f\",\n  \"message\": {\n    \"data\": [\n      {\n        \"value\": \"payment for goods\"\n      }\n    ]\n  }\n}\n
"},{"location":"tutorials/tokens/erc721/#private-message","title":"Private message","text":"
{\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

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.

"},{"location":"tutorials/tokens/erc721/#burn-tokens","title":"Burn tokens","text":"

You may burn a token by specifying the token's tokenIndex. 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.

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn

{\n  \"amount\": 1,\n  \"tokenIndex\": \"1\"\n}\n

Other parameters:

  • You must specify a pool name if you've created more than one pool
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
  • You may specify from if you'd like to burn tokens from a specific identity (default is the same as key)
"},{"location":"tutorials/tokens/erc721/#token-approvals","title":"Token approvals","text":"

You can also approve other wallets to transfer tokens on your behalf with the /approvals API. The important fields in a token approval API request are as follows:

  • approved: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to true. Setting to false can revoke an existing approval.
  • operator: The other account that is allowed to transfer tokens out of the wallet specified in the key field
  • config.tokenIndex: The specific token index within the pool that the operator is allowed to transfer. If 0 or not set, the approval is valid for all tokens.
  • key: The wallet address for the approval. If not set, it defaults to the address of the FireFly node submitting the transaction

Here is an example request that would let the signing account 0x634ee8c7d0894d086c7af1fc8514736aed251528 transfer tokenIndex 2 from my wallet.

"},{"location":"tutorials/tokens/erc721/#request_5","title":"Request","text":"

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals

{\n  \"operator\": \"0x634ee8c7d0894d086c7af1fc8514736aed251528\",\n  \"config\": {\n    \"tokenIndex\": \"2\"\n  }\n}\n
"},{"location":"tutorials/tokens/erc721/#response_4","title":"Response","text":"
{\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
"},{"location":"tutorials/tokens/erc721/#use-metamask","title":"Use Metamask","text":"

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.

"},{"location":"tutorials/tokens/erc721/#configure-a-new-network","title":"Configure a new network","text":"

The first thing we need to do is tell Metamask how to connect to our local blockchain node. To do that:

  • Click your account icon

  • In the drop down menu, click Settings

  • On the left hand side of the page, click Networks

  • Click the Add a network button

  • Fill in the network details:

  • Network Name: FireFly (could be any name)
  • New RPC URL: http://127.0.0.1:5100
  • Chain ID: 2021
  • Currency Symbol: ETH
  • Click Save
"},{"location":"tutorials/tokens/erc721/#import-tokens","title":"Import tokens","text":"

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.

  • Click on Import tokens

  • Enter the Ethereum address of the contract

  • Enter a Token Symbol (can be anything you want)
  • Click Add Custom Token

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 GET to http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools to lookup your configured token pools.

"},{"location":"tutorials/tokens/erc721/#transfer-tokens","title":"Transfer tokens","text":"

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.

After a couple seconds, you should see your token show up in your Metamask wallet.

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.

"}]} \ No newline at end of file diff --git a/v1.3.1/sitemap.xml b/v1.3.1/sitemap.xml new file mode 100644 index 000000000..0f8724efd --- /dev/null +++ b/v1.3.1/sitemap.xml @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/v1.3.1/sitemap.xml.gz b/v1.3.1/sitemap.xml.gz new file mode 100644 index 000000000..a73fcb5fe Binary files /dev/null and b/v1.3.1/sitemap.xml.gz differ diff --git a/v1.3.1/stylesheets/extra.css b/v1.3.1/stylesheets/extra.css new file mode 100644 index 000000000..d56bec0e8 --- /dev/null +++ b/v1.3.1/stylesheets/extra.css @@ -0,0 +1,3 @@ +:root { + --md-primary-fg-color: #472EE0; + } \ No newline at end of file diff --git a/v1.3.1/swagger/index.html b/v1.3.1/swagger/index.html new file mode 100644 index 000000000..16cbd0206 --- /dev/null +++ b/v1.3.1/swagger/index.html @@ -0,0 +1,3428 @@ + + + + + + + + + + + + + + + + + + + + + + + API Spec - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

API Spec

+ +

This is the FireFly OpenAPI Specification document generated by FireFly

+

Note: The 'Try it out' buttons will not work on this page because it's not running against a live version of FireFly. To actually try it out, we recommend using the FireFly CLI 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

+

+ + +
+ + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/swagger/swagger.yaml b/v1.3.1/swagger/swagger.yaml new file mode 100644 index 000000000..60a2e7b24 --- /dev/null +++ b/v1.3.1/swagger/swagger.yaml @@ -0,0 +1,44709 @@ +components: {} +info: + title: Hyperledger FireFly + version: "1.0" +openapi: 3.0.2 +paths: + /apis: + get: + description: Gets a list of contract APIs that have been published + operationId: getContractAPIs + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: networkname + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: published + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used + to publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the + API + type: string + namespace: + description: The namespace of the contract API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + published: + description: Indicates if the API is published to other members + of the multiparty network + type: boolean + urls: + description: The URLs to use to access the API + properties: + api: + description: The URL to use to invoke the API + type: string + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates and broadcasts a new custom smart contract API + operationId: postNewContractAPI + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: When true the definition will be published to all other members + of the multiparty network + in: query + name: publish + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + name: + description: The name that is used in the URL to access the API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + published: + description: Indicates if the API is published to other members + of the multiparty network + type: boolean + urls: + description: The URLs to use to access the API + properties: + api: + description: The URL to use to invoke the API + type: string + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + published: + description: Indicates if the API is published to other members + of the multiparty network + type: boolean + urls: + description: The URLs to use to access the API + properties: + api: + description: The URL to use to invoke the API + type: string + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /apis/{apiName}: + delete: + description: Delete a contract API + operationId: deleteContractAPI + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Default Namespace + get: + description: Gets information about a contract API, including the URLs for the + OpenAPI Spec and Swagger UI for the API + operationId: getContractAPIByName + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + published: + description: Indicates if the API is published to other members + of the multiparty network + type: boolean + urls: + description: The URLs to use to access the API + properties: + api: + description: The URL to use to invoke the API + type: string + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + put: + description: The ID of the contract API + operationId: putContractAPI + parameters: + - description: The name of the contract API + in: path + name: id + required: true + schema: + example: id + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + name: + description: The name that is used in the URL to access the API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + published: + description: Indicates if the API is published to other members + of the multiparty network + type: boolean + urls: + description: The URLs to use to access the API + properties: + api: + description: The URL to use to invoke the API + type: string + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + published: + description: Indicates if the API is published to other members + of the multiparty network + type: boolean + urls: + description: The URLs to use to access the API + properties: + api: + description: The URL to use to invoke the API + type: string + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /apis/{apiName}/interface: + get: + description: Gets a contract interface for a contract API + operationId: getContractAPIInterface + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /apis/{apiName}/invoke/{methodPath}: + post: + description: Invokes a method on a smart contract API. Performs a blockchain + transaction. + operationId: postContractAPIInvoke + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a method on a smart + contract + in: path + name: methodPath + required: true + schema: + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + message: + description: You can specify a message to correlate with the invocation, + which can be of type broadcast or private. Your specified method + must support on-chain/off-chain correlation by taking a data input + on the call + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /apis/{apiName}/listeners/{eventPath}: + get: + description: Gets a list of contract listeners + operationId: getContractAPIListeners + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a event on a smart + contract + in: path + name: eventPath + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: backendid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: filters + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: location + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: signature + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: 'Deprecated: Please use ''event'' in the array + of ''filters'' instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from + the referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument + definitions + items: + description: An array of event parameter/argument + definitions + properties: + name: + description: The name of the parameter. Note + that parameters must be ordered correctly + on the FFI, according to the order in the + blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + interface: + description: A reference to an existing FFI, containing + pre-registered type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + signature: + description: The stringified signature of the event and + location, as computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array + of ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: A concatenation of all the stringified signature + of the event and location, as computed by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates a new blockchain listener for events emitted by custom + smart contracts + operationId: postContractAPIListeners + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a event on a smart + contract + in: path + name: eventPath + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + event: + description: 'Deprecated: Please use ''event'' in the array of ''filters'' + instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + location: + description: 'Deprecated: Please use ''location'' in the array of + ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + options: + description: Options that control how the listener subscribes to + events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + topic: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: 'Deprecated: Please use ''event'' in the array of + ''filters'' instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from + the referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument + definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the + FFI, according to the order in the blockchain + smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + interface: + description: A reference to an existing FFI, containing + pre-registered type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + signature: + description: The stringified signature of the event and + location, as computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array + of ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: A concatenation of all the stringified signature + of the event and location, as computed by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /apis/{apiName}/publish: + post: + description: Publish a contract API to all other members of the multiparty network + operationId: postContractAPIPublish + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + networkName: + description: An optional name to be used for publishing this definition + to the multiparty network, which may differ from the local name + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /apis/{apiName}/query/{methodPath}: + post: + description: Queries a method on a smart contract API. Performs a read-only + query. + operationId: postContractAPIQuery + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a method on a smart + contract + in: path + name: methodPath + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + additionalProperties: {} + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /batches: + get: + description: Gets a list of message batches + operationId: getBatches + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: node + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: payloadref + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + author: + description: The DID of identity of the submitter + type: string + confirmed: + description: The time when the batch was confirmed + format: date-time + type: string + created: + description: The time the batch was sealed + format: date-time + type: string + group: + description: The privacy group the batch is sent to, for private + batches + format: byte + type: string + hash: + description: The hash of the manifest of the batch + format: byte + type: string + id: + description: The UUID of the batch + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + manifest: + description: The manifest of the batch + namespace: + description: The namespace of the batch + type: string + node: + description: The UUID of the node that generated the batch + format: uuid + type: string + tx: + description: The FireFly transaction associated with this batch + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of the batch + enum: + - broadcast + - private + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /batches/{batchid}: + get: + description: Gets a message batch + operationId: getBatchByID + parameters: + - description: The batch ID + in: path + name: batchid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + author: + description: The DID of identity of the submitter + type: string + confirmed: + description: The time when the batch was confirmed + format: date-time + type: string + created: + description: The time the batch was sealed + format: date-time + type: string + group: + description: The privacy group the batch is sent to, for private + batches + format: byte + type: string + hash: + description: The hash of the manifest of the batch + format: byte + type: string + id: + description: The UUID of the batch + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + manifest: + description: The manifest of the batch + namespace: + description: The namespace of the batch + type: string + node: + description: The UUID of the node that generated the batch + format: uuid + type: string + tx: + description: The FireFly transaction associated with this batch + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of the batch + enum: + - broadcast + - private + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /batches/{batchid}/cancel: + post: + description: Cancel a batch that has failed to dispatch + operationId: postBatchCancel + parameters: + - description: The batch ID + in: path + name: batchid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: {} + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Default Namespace + /blockchainevents: + get: + description: Gets a list of blockchain events + operationId: getBlockchainEvents + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: listener + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: protocolid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: source + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: timestamp + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.blockchainid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + id: + description: The UUID assigned to the event by FireFly + format: uuid + type: string + info: + additionalProperties: + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + type: object + listener: + description: The UUID of the listener that detected this event, + or nil for built-in events in the system namespace + format: uuid + type: string + name: + description: The name of the event in the blockchain smart contract + type: string + namespace: + description: The namespace of the listener that detected this + blockchain event + type: string + output: + additionalProperties: + description: The data output by the event, parsed to JSON + according to the interface of the smart contract + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + type: object + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely on the blockchain (convention for plugins + is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) + type: string + source: + description: The blockchain plugin or token service that detected + the event + type: string + timestamp: + description: The time allocated to this event by the blockchain. + This is the block timestamp for most blockchain connectors + format: date-time + type: string + tx: + description: 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 + properties: + blockchainId: + description: The blockchain transaction ID, in the format + specific to the blockchain involved in the transaction. + Not all FireFly transactions include a blockchain + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /blockchainevents/{id}: + get: + description: Gets a blockchain event + operationId: getBlockchainEventByID + parameters: + - description: The blockchain event ID + in: path + name: id + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID assigned to the event by FireFly + format: uuid + type: string + info: + additionalProperties: + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + description: Detailed blockchain specific information about the + event, as generated by the blockchain connector + type: object + listener: + description: The UUID of the listener that detected this event, + or nil for built-in events in the system namespace + format: uuid + type: string + name: + description: The name of the event in the blockchain smart contract + type: string + namespace: + description: The namespace of the listener that detected this + blockchain event + type: string + output: + additionalProperties: + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + type: object + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely on the blockchain (convention for plugins + is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) + type: string + source: + description: The blockchain plugin or token service that detected + the event + type: string + timestamp: + description: The time allocated to this event by the blockchain. + This is the block timestamp for most blockchain connectors + format: date-time + type: string + tx: + description: 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 + properties: + blockchainId: + description: The blockchain transaction ID, in the format + specific to the blockchain involved in the transaction. + Not all FireFly transactions include a blockchain + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /charts/histogram/{collection}: + get: + description: Gets a JSON object containing statistics data that can be used + to build a graphical representation of recent activity in a given database + collection + operationId: getChartHistogram + parameters: + - description: The collection ID + in: path + name: collection + required: true + schema: + type: string + - description: Start time of the data to be fetched + in: query + name: startTime + schema: + type: string + - description: End time of the data to be fetched + in: query + name: endTime + schema: + type: string + - description: Number of buckets between start time and end time + in: query + name: buckets + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + count: + description: Total count of entries in this time bucket within + the histogram + type: string + isCapped: + description: Indicates whether there are more results in this + bucket that are not being displayed + type: boolean + timestamp: + description: Starting timestamp for the bucket + format: date-time + type: string + types: + description: Array of separate counts for individual types of + record within the bucket + items: + description: Array of separate counts for individual types + of record within the bucket + properties: + count: + description: Count of entries of a given type within a + bucket + type: string + type: + description: Name of the type + type: string + type: object + type: array + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/deploy: + post: + description: Deploy a new smart contract + operationId: postContractDeploy + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + contract: + description: The smart contract to deploy. This should be pre-compiled + if required by the blockchain connector + definition: + description: The definition of the smart contract + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + description: An optional array of inputs passed to the smart contract's + constructor, if applicable + items: + description: An optional array of inputs passed to the smart contract's + constructor, if applicable + type: array + key: + description: The blockchain signing key that will be used to deploy + the contract. Defaults to the first signing key of the organization + that operates the node + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/interfaces: + get: + description: Gets a list of contract interfaces that have been published + operationId: getContractInterfaces + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: networkname + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: published + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: version + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used + to publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used + by the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates and broadcasts a new custom smart contract interface + operationId: postNewContractInterface + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: When true the definition will be published to all other members + of the multiparty network + in: query + name: publish + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart contract + name + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/interfaces/{interfaceId}: + delete: + description: Delete a contract interface + operationId: deleteContractInterface + parameters: + - description: The ID of the contract interface + in: path + name: interfaceId + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Default Namespace + get: + description: Gets a contract interface by its ID + operationId: getContractInterface + parameters: + - description: The ID of the contract interface + in: path + name: interfaceId + required: true + schema: + type: string + - description: When set, the API will return the full FireFly Interface document + including all methods, events, and parameters + in: query + name: fetchchildren + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/interfaces/{name}/{version}: + get: + description: Gets a contract interface by its name and version + operationId: getContractInterfaceByNameAndVersion + parameters: + - description: The name of the contract interface + in: path + name: name + required: true + schema: + type: string + - description: The version of the contract interface + in: path + name: version + required: true + schema: + type: string + - description: When set, the API will return the full FireFly Interface document + including all methods, events, and parameters + in: query + name: fetchchildren + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/interfaces/{name}/{version}/publish: + post: + description: Publish a contract interface to all other members of the multiparty + network + operationId: postContractInterfacePublish + parameters: + - description: The name of the contract interface + in: path + name: name + required: true + schema: + type: string + - description: The version of the contract interface + in: path + name: version + required: true + schema: + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + networkName: + description: An optional name to be used for publishing this definition + to the multiparty network, which may differ from the local name + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/interfaces/generate: + post: + description: A convenience method to convert a blockchain specific smart contract + format into a FireFly Interface format. The specific blockchain plugin in + use must support this functionality. + operationId: postGenerateContractInterface + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: The description of the FFI to be generated. Defaults + to the description extracted by the blockchain specific converter + utility + type: string + input: + description: A blockchain connector specific payload. For example + in Ethereum this is a JSON structure containing an 'abi' array, + and optionally a 'devdocs' array. + name: + description: The name of the FFI to generate + type: string + namespace: + description: The namespace into which the FFI will be generated + type: string + version: + description: The version of the FFI to generate + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/invoke: + post: + description: Invokes a method on a smart contract. Performs a blockchain transaction. + operationId: postContractInvoke + parameters: + - description: When true the HTTP request blocks until the blockchain transaction + is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + errors: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + items: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + interface: + description: The UUID of a method within a pre-configured FireFly + interface (FFI) definition for a smart contract. Required if the + 'method' is omitted. Also see Contract APIs as a way to configure + a dedicated API for your FFI, including all methods and an OpenAPI/Swagger + interface + format: uuid + type: string + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + message: + description: You can specify a message to correlate with the invocation, + which can be of type broadcast or private. Your specified method + must support on-chain/off-chain correlation by taking a data input + on the call + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + method: + description: An in-line FFI method definition for the method to + invoke. Required when FFI is not specified + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + methodPath: + description: The pathname of the method on the specified FFI + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/listeners: + get: + description: Gets a list of contract listeners + operationId: getContractListeners + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: backendid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: filters + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: location + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: signature + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: 'Deprecated: Please use ''event'' in the array + of ''filters'' instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from + the referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument + definitions + items: + description: An array of event parameter/argument + definitions + properties: + name: + description: The name of the parameter. Note + that parameters must be ordered correctly + on the FFI, according to the order in the + blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + interface: + description: A reference to an existing FFI, containing + pre-registered type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + signature: + description: The stringified signature of the event and + location, as computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array + of ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: A concatenation of all the stringified signature + of the event and location, as computed by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates a new blockchain listener for events emitted by custom + smart contracts + operationId: postNewContractListener + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + event: + description: 'Deprecated: Please use ''event'' in the array of ''filters'' + instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + eventPath: + description: 'Deprecated: Please use ''eventPath'' in the array + of ''filters'' instead' + type: string + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from the + referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + type: object + eventPath: + description: When creating a listener from an existing FFI, + this is the pathname of the event on that FFI to be detected + by this listener + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For + example an Ethereum contract address, or a Fabric chaincode + name and channel + type: object + type: array + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array of + ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + options: + description: Options that control how the listener subscribes to + events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + topic: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: 'Deprecated: Please use ''event'' in the array of + ''filters'' instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from + the referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument + definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the + FFI, according to the order in the blockchain + smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + interface: + description: A reference to an existing FFI, containing + pre-registered type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + signature: + description: The stringified signature of the event and + location, as computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array + of ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: A concatenation of all the stringified signature + of the event and location, as computed by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/listeners/{nameOrId}: + delete: + description: Deletes a contract listener referenced by its name or its ID + operationId: deleteContractListener + parameters: + - description: The contract listener name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Default Namespace + get: + description: Gets a contract listener by its name or ID + operationId: getContractListenerByNameOrID + parameters: + - description: The contract listener name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: When set, the API will return additional status information if + available + in: query + name: fetchstatus + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: 'Deprecated: Please use ''event'' in the array of + ''filters'' instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from + the referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument + definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the + FFI, according to the order in the blockchain + smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + interface: + description: A reference to an existing FFI, containing + pre-registered type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + signature: + description: The stringified signature of the event and + location, as computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array + of ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: A concatenation of all the stringified signature + of the event and location, as computed by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/listeners/signature: + post: + description: Calculates the hash of a blockchain listener filters and events + operationId: postContractListenerSignature + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + event: + description: 'Deprecated: Please use ''event'' in the array of ''filters'' + instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + eventPath: + description: 'Deprecated: Please use ''eventPath'' in the array + of ''filters'' instead' + type: string + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from the + referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + type: object + eventPath: + description: When creating a listener from an existing FFI, + this is the pathname of the event on that FFI to be detected + by this listener + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For + example an Ethereum contract address, or a Fabric chaincode + name and channel + type: object + type: array + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array of + ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + options: + description: Options that control how the listener subscribes to + events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + topic: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + signature: + description: A concatenation of all the stringified signature + of the event and location, as computed by the blockchain plugin + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/query: + post: + description: Queries a method on a smart contract. Performs a read-only query. + operationId: postContractQuery + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + errors: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + items: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + interface: + description: The UUID of a method within a pre-configured FireFly + interface (FFI) definition for a smart contract. Required if the + 'method' is omitted. Also see Contract APIs as a way to configure + a dedicated API for your FFI, including all methods and an OpenAPI/Swagger + interface + format: uuid + type: string + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + method: + description: An in-line FFI method definition for the method to + invoke. Required when FFI is not specified + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + methodPath: + description: The pathname of the method on the specified FFI + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + additionalProperties: {} + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /data: + get: + description: Gets a list of data items + operationId: getData + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.path + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.public + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.size + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datatype.name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datatype.version + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: public + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: validator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: value + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + path: + description: If a name is specified, this field stores the + '/' prefixed and separated path extracted from the full + name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the + value and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates a new data item in this FireFly node + operationId: postData + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + datatype: + description: The optional datatype to use for validation of the + in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON type + - object, array, string, number or boolean + type: object + multipart/form-data: + schema: + properties: + autometa: + description: Success + type: string + datatype.name: + description: Success + type: string + datatype.version: + description: Success + type: string + filename.ext: + format: binary + type: string + metadata: + description: Success + type: string + validator: + description: Success + type: string + type: object + responses: + "201": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + path: + description: If a name is specified, this field stores the + '/' prefixed and separated path extracted from the full + name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /data/{dataid}: + delete: + description: Deletes a data item by its ID, including metadata about this item + operationId: deleteData + parameters: + - description: The data item ID + in: path + name: dataid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Default Namespace + get: + description: Gets a data item by its ID, including metadata about this item + operationId: getDataByID + parameters: + - description: The data item ID + in: path + name: dataid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + path: + description: If a name is specified, this field stores the + '/' prefixed and separated path extracted from the full + name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /data/{dataid}/blob: + get: + description: Downloads the original file that was previously uploaded or received + operationId: getDataBlob + parameters: + - description: The data item ID + in: path + name: dataid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: rejectreason + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + format: byte + type: string + description: Success + default: + description: "" + tags: + - Default Namespace + /data/{dataid}/blob/publish: + post: + description: Publishes the binary blob attachment stored in your local data + exchange, to shared storage + operationId: postDataBlobPublish + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + path: + description: If a name is specified, this field stores the + '/' prefixed and separated path extracted from the full + name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /data/{dataid}/messages: + get: + description: Gets a list of the messages associated with a data item + operationId: getDataMsgs + parameters: + - description: The data item ID + in: path + name: dataid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: rejectreason + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /data/{dataid}/value: + get: + description: Downloads the JSON value of the data resource, without the associated + metadata + operationId: getDataValue + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: rejectreason + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + format: byte + type: string + description: Success + default: + description: "" + tags: + - Default Namespace + /data/{dataid}/value/publish: + post: + description: Publishes the JSON value from the specified data resource, to shared + storage + operationId: postDataValuePublish + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + path: + description: If a name is specified, this field stores the + '/' prefixed and separated path extracted from the full + name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /datasubpaths/{parent}: + get: + description: Gets a list of path names of named blob data, underneath a given + parent path ('/' path prefixes are automatically pre-prepended) + operationId: getDataSubPaths + parameters: + - description: The parent path to query + in: path + name: parent + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + type: string + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /datatypes: + get: + description: Gets a list of datatypes that have been published + operationId: getDatatypes + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: validator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: version + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used + to publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions + can exist with the same name. Use of semantic versioning is + encourages, such as v1.0.1 + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates and broadcasts a new datatype + operationId: postNewDatatype + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + name: + description: The name of the datatype + type: string + validator: + description: The validator that should be used to verify this datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /datatypes/{name}/{version}: + get: + description: Gets a datatype by its name and version + operationId: getDatatypeByName + parameters: + - description: The name of the datatype + in: path + name: name + required: true + schema: + type: string + - description: The version of the datatype + in: path + name: version + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /events: + get: + description: Gets a list of events + operationId: getEvents + parameters: + - description: When set, the API will return the record that this item references + in its 'reference' field + in: query + name: fetchreferences + schema: + example: "true" + type: string + - description: When set, the API will return the record that this item references + in its 'reference' field + in: query + name: fetchreference + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: correlator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: reference + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part + of. Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /events/{eid}: + get: + description: Gets an event by its ID + operationId: getEventByID + parameters: + - description: The event ID + in: path + name: eid + required: true + schema: + type: string + - description: When set, the API will return the record that this item references + in its 'reference' field + in: query + name: fetchreference + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part of. + Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /groups: + get: + description: Gets a list of groups + operationId: getGroups + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: ledger + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time when the group was first used to send + a message in the network + format: date-time + type: string + hash: + description: The identifier hash of this group. Derived from + the name and group members + format: byte + type: string + localNamespace: + description: The local namespace of the group + type: string + members: + description: The list of members in this privacy group + items: + description: The list of members in this privacy group + properties: + identity: + description: The DID of the group member + type: string + node: + description: The UUID of the node that receives a copy + of the off-chain message for the identity + format: uuid + type: string + type: object + type: array + message: + description: The message used to broadcast this group privately + to the members + format: uuid + type: string + name: + description: The optional name of the group, allowing multiple + unique groups to exist with the same list of recipients + type: string + namespace: + description: The namespace of the group within the multiparty + network + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /groups/{hash}: + get: + description: Gets a group by its ID (hash) + operationId: getGroupByHash + parameters: + - description: The hash of the group + in: path + name: hash + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time when the group was first used to send a + message in the network + format: date-time + type: string + hash: + description: The identifier hash of this group. Derived from the + name and group members + format: byte + type: string + localNamespace: + description: The local namespace of the group + type: string + members: + description: The list of members in this privacy group + items: + description: The list of members in this privacy group + properties: + identity: + description: The DID of the group member + type: string + node: + description: The UUID of the node that receives a copy of + the off-chain message for the identity + format: uuid + type: string + type: object + type: array + message: + description: The message used to broadcast this group privately + to the members + format: uuid + type: string + name: + description: The optional name of the group, allowing multiple + unique groups to exist with the same list of recipients + type: string + namespace: + description: The namespace of the group within the multiparty + network + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /identities: + get: + description: Gets a list of all identities that have been registered in the + namespace + operationId: getIdentities + parameters: + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to + prove data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum + address, or Fabric MSP identifier + type: string + type: object + type: array + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Registers a new identity in the network + operationId: postNewIdentity + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + key: + description: The blockchain signing key to use to make the claim + to the identity. Must be available to the local node to sign the + identity claim. Will become a verifier on the established identity + type: string + name: + description: The name of the identity. The name must be unique within + the type and namespace + type: string + parent: + description: On input the parent can be specified directly as the + UUID of and existing identity, or as a DID to resolve to that + identity, or an organization name. The parent must already have + been registered, and its blockchain signing key must be available + to the local node to sign the verification + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /identities/{did}: + get: + description: Gets an identity by its ID + operationId: getIdentityByID + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + example: id + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + patch: + description: Updates an identity + operationId: patchUpdateIdentity + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /identities/{iid}/did: + get: + description: Gets the DID for an identity based on its ID + operationId: getIdentityDID + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + example: id + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + '@context': + description: See https://www.w3.org/TR/did-core/#json-ld + items: + description: See https://www.w3.org/TR/did-core/#json-ld + type: string + type: array + authentication: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + type: array + id: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + verificationMethod: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + properties: + blockchainAcountId: + description: For blockchains like Ethereum that represent + signing identities directly by their public key summarized + in an account string + type: string + controller: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + dataExchangePeerID: + description: A string provided by your Data Exchange plugin, + that it uses a technology specific mechanism to validate + against when messages arrive from this identity + type: string + id: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + mspIdentityString: + description: For Hyperledger Fabric where the signing identity + is represented by an MSP identifier (containing X509 certificate + DN strings) that were validated by your local MSP + type: string + type: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /identities/{iid}/verifiers: + get: + description: Gets the verifiers for an identity + operationId: getIdentityVerifiers + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + example: id + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: identity + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: value + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time this verifier was created on this node + format: date-time + type: string + hash: + description: Hash used as a globally consistent identifier for + this namespace + type + value combination on every node in + the network + format: byte + type: string + identity: + description: The UUID of the parent identity that has claimed + this verifier + format: uuid + type: string + namespace: + description: The namespace of the verifier + type: string + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /messages: + get: + description: Gets a list of messages + operationId: getMsgs + parameters: + - description: Fetch the data and include it in the messages returned + in: query + name: fetchdata + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: rejectreason + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + batch: + description: The UUID of the batch in which the message was + pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the + message. Derived from the array of data ids+hashes attached + to this message + format: byte + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce + is assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on + the rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver + this message + format: uuid + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/{msgid}: + get: + description: Gets a message by its ID + operationId: getMsgByID + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: Fetch the data and include it in the messages returned + in: query + name: fetchdata + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + properties: + blob: + description: An optional in-line hash reference to a previously + uploaded binary data blob + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached + to the blob, commonly used as a path/filename, and + indexed for search + type: string + path: + description: If a name is specified, this field stores + the '/' prefixed and separated path extracted from + the full name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will be + picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/{msgid}/data: + get: + description: Gets the list of data items that are attached to a message + operationId: getMsgData + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + path: + description: If a name is specified, this field stores the + '/' prefixed and separated path extracted from the full + name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the + value and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/{msgid}/events: + get: + description: Gets the list of events for a message + operationId: getMsgEvents + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: correlator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: reference + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part + of. Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/{msgid}/transaction: + get: + description: Gets the transaction for a message + operationId: getMsgTxn + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + blockchainIds: + description: 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 + items: + description: 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 + type: string + type: array + created: + description: 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 + format: date-time + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + idempotencyKey: + description: An optional unique identifier for a transaction. + Cannot be duplicated within a namespace, thus allowing idempotent + submission of transactions to the API + type: string + namespace: + description: The namespace of the FireFly transaction + type: string + type: + description: The type of the FireFly transaction + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/broadcast: + post: + description: Broadcasts a message to all members in the network + operationId: postNewMessageBroadcast + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation of + the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON + type - object, array, string, number or boolean + type: object + type: array + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the message + to the applications that process it + type: string + topics: + description: A message topic associates this message with an + ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver this + message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/private: + post: + description: Privately sends a message to one or more members in the network + operationId: postNewMessagePrivate + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation of + the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON + type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive a + copy of the off-chain message for the identity. The + first applicable node for the identity will be picked + automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list of + the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the message + to the applications that process it + type: string + topics: + description: A message topic associates this message with an + ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver this + message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/requestreply: + post: + description: Sends a message with a blocking HTTP request, waits for a reply + to that message, then sends the reply as the HTTP response. + operationId: postNewMessageRequestReply + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation of + the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON + type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive a + copy of the off-chain message for the identity. The + first applicable node for the identity will be picked + automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list of + the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the message + to the applications that process it + type: string + topics: + description: A message topic associates this message with an + ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver this + message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + properties: + blob: + description: An optional in-line hash reference to a previously + uploaded binary data blob + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached + to the blob, commonly used as a path/filename, and + indexed for search + type: string + path: + description: If a name is specified, this field stores + the '/' prefixed and separated path extracted from + the full name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will be + picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /namespaces: + get: + description: Gets a list of namespaces + operationId: getNamespaces + parameters: + - description: When set, the API will return namespaces even if they are not + yet initialized, including in error cases where an initializationError is + included + in: query + name: includeinitializing + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the namespace was created + format: date-time + type: string + description: + description: A description of the namespace + type: string + initializationError: + description: Set to a non-empty string in the case that the + namespace is currently failing to initialize + type: string + initializing: + description: Set to true if the namespace is still initializing + type: boolean + name: + description: The local namespace name + type: string + networkName: + description: The shared namespace name within the multiparty + network + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Global + /namespaces/{ns}: + get: + description: Gets a namespace + operationId: getNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the namespace was created + format: date-time + type: string + description: + description: A description of the namespace + type: string + name: + description: The local namespace name + type: string + networkName: + description: The shared namespace name within the multiparty network + type: string + type: object + description: Success + default: + description: "" + tags: + - Global + /namespaces/{ns}/apis: + get: + description: Gets a list of contract APIs that have been published + operationId: getContractAPIsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: networkname + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: published + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used + to publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the + API + type: string + namespace: + description: The namespace of the contract API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + published: + description: Indicates if the API is published to other members + of the multiparty network + type: boolean + urls: + description: The URLs to use to access the API + properties: + api: + description: The URL to use to invoke the API + type: string + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates and broadcasts a new custom smart contract API + operationId: postNewContractAPINamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: When true the definition will be published to all other members + of the multiparty network + in: query + name: publish + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + name: + description: The name that is used in the URL to access the API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + published: + description: Indicates if the API is published to other members + of the multiparty network + type: boolean + urls: + description: The URLs to use to access the API + properties: + api: + description: The URL to use to invoke the API + type: string + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + published: + description: Indicates if the API is published to other members + of the multiparty network + type: boolean + urls: + description: The URLs to use to access the API + properties: + api: + description: The URL to use to invoke the API + type: string + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/apis/{apiName}: + delete: + description: Delete a contract API + operationId: deleteContractAPINamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Non-Default Namespace + get: + description: Gets information about a contract API, including the URLs for the + OpenAPI Spec and Swagger UI for the API + operationId: getContractAPIByNameNamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + published: + description: Indicates if the API is published to other members + of the multiparty network + type: boolean + urls: + description: The URLs to use to access the API + properties: + api: + description: The URL to use to invoke the API + type: string + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + put: + description: The ID of the contract API + operationId: putContractAPINamespace + parameters: + - description: The name of the contract API + in: path + name: id + required: true + schema: + example: id + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + name: + description: The name that is used in the URL to access the API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + published: + description: Indicates if the API is published to other members + of the multiparty network + type: boolean + urls: + description: The URLs to use to access the API + properties: + api: + description: The URL to use to invoke the API + type: string + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + networkName: + description: The published name of the API within the multiparty + network + type: string + published: + description: Indicates if the API is published to other members + of the multiparty network + type: boolean + urls: + description: The URLs to use to access the API + properties: + api: + description: The URL to use to invoke the API + type: string + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/apis/{apiName}/interface: + get: + description: Gets a contract interface for a contract API + operationId: getContractAPIInterfaceNamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/apis/{apiName}/invoke/{methodPath}: + post: + description: Invokes a method on a smart contract API. Performs a blockchain + transaction. + operationId: postContractAPIInvokeNamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a method on a smart + contract + in: path + name: methodPath + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + errors: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + items: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + interface: + description: The UUID of a method within a pre-configured FireFly + interface (FFI) definition for a smart contract. Required if the + 'method' is omitted. Also see Contract APIs as a way to configure + a dedicated API for your FFI, including all methods and an OpenAPI/Swagger + interface + format: uuid + type: string + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + message: + description: You can specify a message to correlate with the invocation, + which can be of type broadcast or private. Your specified method + must support on-chain/off-chain correlation by taking a data input + on the call + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + method: + description: An in-line FFI method definition for the method to + invoke. Required when FFI is not specified + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + methodPath: + description: The pathname of the method on the specified FFI + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/apis/{apiName}/listeners/{eventPath}: + get: + description: Gets a list of contract listeners + operationId: getContractAPIListenersNamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a event on a smart + contract + in: path + name: eventPath + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: backendid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: filters + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: location + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: signature + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: 'Deprecated: Please use ''event'' in the array + of ''filters'' instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from + the referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument + definitions + items: + description: An array of event parameter/argument + definitions + properties: + name: + description: The name of the parameter. Note + that parameters must be ordered correctly + on the FFI, according to the order in the + blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + interface: + description: A reference to an existing FFI, containing + pre-registered type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + signature: + description: The stringified signature of the event and + location, as computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array + of ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: A concatenation of all the stringified signature + of the event and location, as computed by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates a new blockchain listener for events emitted by custom + smart contracts + operationId: postContractAPIListenersNamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a event on a smart + contract + in: path + name: eventPath + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + event: + description: 'Deprecated: Please use ''event'' in the array of ''filters'' + instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from the + referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For + example an Ethereum contract address, or a Fabric chaincode + name and channel + type: object + type: array + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array of + ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + options: + description: Options that control how the listener subscribes to + events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + topic: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: 'Deprecated: Please use ''event'' in the array of + ''filters'' instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from + the referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument + definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the + FFI, according to the order in the blockchain + smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + interface: + description: A reference to an existing FFI, containing + pre-registered type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + signature: + description: The stringified signature of the event and + location, as computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array + of ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: A concatenation of all the stringified signature + of the event and location, as computed by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/apis/{apiName}/publish: + post: + description: Publish a contract API to all other members of the multiparty network + operationId: postContractAPIPublishNamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + networkName: + description: An optional name to be used for publishing this definition + to the multiparty network, which may differ from the local name + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/apis/{apiName}/query/{methodPath}: + post: + description: Queries a method on a smart contract API. Performs a read-only + query. + operationId: postContractAPIQueryNamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a method on a smart + contract + in: path + name: methodPath + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + errors: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + items: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + interface: + description: The UUID of a method within a pre-configured FireFly + interface (FFI) definition for a smart contract. Required if the + 'method' is omitted. Also see Contract APIs as a way to configure + a dedicated API for your FFI, including all methods and an OpenAPI/Swagger + interface + format: uuid + type: string + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + message: + description: You can specify a message to correlate with the invocation, + which can be of type broadcast or private. Your specified method + must support on-chain/off-chain correlation by taking a data input + on the call + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + method: + description: An in-line FFI method definition for the method to + invoke. Required when FFI is not specified + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + methodPath: + description: The pathname of the method on the specified FFI + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + additionalProperties: {} + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/batches: + get: + description: Gets a list of message batches + operationId: getBatchesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: node + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: payloadref + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + author: + description: The DID of identity of the submitter + type: string + confirmed: + description: The time when the batch was confirmed + format: date-time + type: string + created: + description: The time the batch was sealed + format: date-time + type: string + group: + description: The privacy group the batch is sent to, for private + batches + format: byte + type: string + hash: + description: The hash of the manifest of the batch + format: byte + type: string + id: + description: The UUID of the batch + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + manifest: + description: The manifest of the batch + namespace: + description: The namespace of the batch + type: string + node: + description: The UUID of the node that generated the batch + format: uuid + type: string + tx: + description: The FireFly transaction associated with this batch + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of the batch + enum: + - broadcast + - private + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/batches/{batchid}: + get: + description: Gets a message batch + operationId: getBatchByIDNamespace + parameters: + - description: The batch ID + in: path + name: batchid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + author: + description: The DID of identity of the submitter + type: string + confirmed: + description: The time when the batch was confirmed + format: date-time + type: string + created: + description: The time the batch was sealed + format: date-time + type: string + group: + description: The privacy group the batch is sent to, for private + batches + format: byte + type: string + hash: + description: The hash of the manifest of the batch + format: byte + type: string + id: + description: The UUID of the batch + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + manifest: + description: The manifest of the batch + namespace: + description: The namespace of the batch + type: string + node: + description: The UUID of the node that generated the batch + format: uuid + type: string + tx: + description: The FireFly transaction associated with this batch + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of the batch + enum: + - broadcast + - private + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/batches/{batchid}/cancel: + post: + description: Cancel a batch that has failed to dispatch + operationId: postBatchCancelNamespace + parameters: + - description: The batch ID + in: path + name: batchid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: {} + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/blockchainevents: + get: + description: Gets a list of blockchain events + operationId: getBlockchainEventsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: listener + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: protocolid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: source + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: timestamp + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.blockchainid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + id: + description: The UUID assigned to the event by FireFly + format: uuid + type: string + info: + additionalProperties: + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + type: object + listener: + description: The UUID of the listener that detected this event, + or nil for built-in events in the system namespace + format: uuid + type: string + name: + description: The name of the event in the blockchain smart contract + type: string + namespace: + description: The namespace of the listener that detected this + blockchain event + type: string + output: + additionalProperties: + description: The data output by the event, parsed to JSON + according to the interface of the smart contract + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + type: object + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely on the blockchain (convention for plugins + is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) + type: string + source: + description: The blockchain plugin or token service that detected + the event + type: string + timestamp: + description: The time allocated to this event by the blockchain. + This is the block timestamp for most blockchain connectors + format: date-time + type: string + tx: + description: 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 + properties: + blockchainId: + description: The blockchain transaction ID, in the format + specific to the blockchain involved in the transaction. + Not all FireFly transactions include a blockchain + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/blockchainevents/{id}: + get: + description: Gets a blockchain event + operationId: getBlockchainEventByIDNamespace + parameters: + - description: The blockchain event ID + in: path + name: id + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID assigned to the event by FireFly + format: uuid + type: string + info: + additionalProperties: + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + description: Detailed blockchain specific information about the + event, as generated by the blockchain connector + type: object + listener: + description: The UUID of the listener that detected this event, + or nil for built-in events in the system namespace + format: uuid + type: string + name: + description: The name of the event in the blockchain smart contract + type: string + namespace: + description: The namespace of the listener that detected this + blockchain event + type: string + output: + additionalProperties: + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + type: object + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely on the blockchain (convention for plugins + is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) + type: string + source: + description: The blockchain plugin or token service that detected + the event + type: string + timestamp: + description: The time allocated to this event by the blockchain. + This is the block timestamp for most blockchain connectors + format: date-time + type: string + tx: + description: 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 + properties: + blockchainId: + description: The blockchain transaction ID, in the format + specific to the blockchain involved in the transaction. + Not all FireFly transactions include a blockchain + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/charts/histogram/{collection}: + get: + description: Gets a JSON object containing statistics data that can be used + to build a graphical representation of recent activity in a given database + collection + operationId: getChartHistogramNamespace + parameters: + - description: The collection ID + in: path + name: collection + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Start time of the data to be fetched + in: query + name: startTime + schema: + type: string + - description: End time of the data to be fetched + in: query + name: endTime + schema: + type: string + - description: Number of buckets between start time and end time + in: query + name: buckets + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + count: + description: Total count of entries in this time bucket within + the histogram + type: string + isCapped: + description: Indicates whether there are more results in this + bucket that are not being displayed + type: boolean + timestamp: + description: Starting timestamp for the bucket + format: date-time + type: string + types: + description: Array of separate counts for individual types of + record within the bucket + items: + description: Array of separate counts for individual types + of record within the bucket + properties: + count: + description: Count of entries of a given type within a + bucket + type: string + type: + description: Name of the type + type: string + type: object + type: array + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/deploy: + post: + description: Deploy a new smart contract + operationId: postContractDeployNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + contract: + description: The smart contract to deploy. This should be pre-compiled + if required by the blockchain connector + definition: + description: The definition of the smart contract + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + description: An optional array of inputs passed to the smart contract's + constructor, if applicable + items: + description: An optional array of inputs passed to the smart contract's + constructor, if applicable + type: array + key: + description: The blockchain signing key that will be used to deploy + the contract. Defaults to the first signing key of the organization + that operates the node + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/interfaces: + get: + description: Gets a list of contract interfaces that have been published + operationId: getContractInterfacesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: networkname + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: published + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: version + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used + to publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used + by the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates and broadcasts a new custom smart contract interface + operationId: postNewContractInterfaceNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: When true the definition will be published to all other members + of the multiparty network + in: query + name: publish + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart contract + name + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/interfaces/{interfaceId}: + delete: + description: Delete a contract interface + operationId: deleteContractInterfaceNamespace + parameters: + - description: The ID of the contract interface + in: path + name: interfaceId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Non-Default Namespace + get: + description: Gets a contract interface by its ID + operationId: getContractInterfaceNamespace + parameters: + - description: The ID of the contract interface + in: path + name: interfaceId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the full FireFly Interface document + including all methods, events, and parameters + in: query + name: fetchchildren + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/interfaces/{name}/{version}: + get: + description: Gets a contract interface by its name and version + operationId: getContractInterfaceByNameAndVersionNamespace + parameters: + - description: The name of the contract interface + in: path + name: name + required: true + schema: + type: string + - description: The version of the contract interface + in: path + name: version + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the full FireFly Interface document + including all methods, events, and parameters + in: query + name: fetchchildren + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/interfaces/{name}/{version}/publish: + post: + description: Publish a contract interface to all other members of the multiparty + network + operationId: postContractInterfacePublishNamespace + parameters: + - description: The name of the contract interface + in: path + name: name + required: true + schema: + type: string + - description: The version of the contract interface + in: path + name: version + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + networkName: + description: An optional name to be used for publishing this definition + to the multiparty network, which may differ from the local name + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/interfaces/generate: + post: + description: A convenience method to convert a blockchain specific smart contract + format into a FireFly Interface format. The specific blockchain plugin in + use must support this functionality. + operationId: postGenerateContractInterfaceNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: The description of the FFI to be generated. Defaults + to the description extracted by the blockchain specific converter + utility + type: string + input: + description: A blockchain connector specific payload. For example + in Ethereum this is a JSON structure containing an 'abi' array, + and optionally a 'devdocs' array. + name: + description: The name of the FFI to generate + type: string + namespace: + description: The namespace into which the FFI will be generated + type: string + version: + description: The version of the FFI to generate + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + networkName: + description: The published name of the FFI within the multiparty + network + type: string + published: + description: Indicates if the FFI is published to other members + of the multiparty network + type: boolean + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/invoke: + post: + description: Invokes a method on a smart contract. Performs a blockchain transaction. + operationId: postContractInvokeNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the blockchain transaction + is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + errors: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + items: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + interface: + description: The UUID of a method within a pre-configured FireFly + interface (FFI) definition for a smart contract. Required if the + 'method' is omitted. Also see Contract APIs as a way to configure + a dedicated API for your FFI, including all methods and an OpenAPI/Swagger + interface + format: uuid + type: string + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + message: + description: You can specify a message to correlate with the invocation, + which can be of type broadcast or private. Your specified method + must support on-chain/off-chain correlation by taking a data input + on the call + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + method: + description: An in-line FFI method definition for the method to + invoke. Required when FFI is not specified + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + methodPath: + description: The pathname of the method on the specified FFI + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/listeners: + get: + description: Gets a list of contract listeners + operationId: getContractListenersNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: backendid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: filters + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: location + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: signature + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: 'Deprecated: Please use ''event'' in the array + of ''filters'' instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from + the referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument + definitions + items: + description: An array of event parameter/argument + definitions + properties: + name: + description: The name of the parameter. Note + that parameters must be ordered correctly + on the FFI, according to the order in the + blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + interface: + description: A reference to an existing FFI, containing + pre-registered type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + signature: + description: The stringified signature of the event and + location, as computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array + of ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: A concatenation of all the stringified signature + of the event and location, as computed by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates a new blockchain listener for events emitted by custom + smart contracts + operationId: postNewContractListenerNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + event: + description: 'Deprecated: Please use ''event'' in the array of ''filters'' + instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + eventPath: + description: 'Deprecated: Please use ''eventPath'' in the array + of ''filters'' instead' + type: string + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from the + referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + type: object + eventPath: + description: When creating a listener from an existing FFI, + this is the pathname of the event on that FFI to be detected + by this listener + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For + example an Ethereum contract address, or a Fabric chaincode + name and channel + type: object + type: array + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array of + ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + options: + description: Options that control how the listener subscribes to + events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + topic: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: 'Deprecated: Please use ''event'' in the array of + ''filters'' instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from + the referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument + definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the + FFI, according to the order in the blockchain + smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + interface: + description: A reference to an existing FFI, containing + pre-registered type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + signature: + description: The stringified signature of the event and + location, as computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array + of ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: A concatenation of all the stringified signature + of the event and location, as computed by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/listeners/{nameOrId}: + delete: + description: Deletes a contract listener referenced by its name or its ID + operationId: deleteContractListenerNamespace + parameters: + - description: The contract listener name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Non-Default Namespace + get: + description: Gets a contract listener by its name or ID + operationId: getContractListenerByNameOrIDNamespace + parameters: + - description: The contract listener name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return additional status information if + available + in: query + name: fetchstatus + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: 'Deprecated: Please use ''event'' in the array of + ''filters'' instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from + the referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields + about this event from the original smart contract. + Used by the blockchain plugin and for documentation + generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument + definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the + FFI, according to the order in the blockchain + smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + interface: + description: A reference to an existing FFI, containing + pre-registered type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + signature: + description: The stringified signature of the event and + location, as computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array + of ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: A concatenation of all the stringified signature + of the event and location, as computed by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/listeners/signature: + post: + description: Calculates the hash of a blockchain listener filters and events + operationId: postContractListenerSignatureNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + event: + description: 'Deprecated: Please use ''event'' in the array of ''filters'' + instead' + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + eventPath: + description: 'Deprecated: Please use ''eventPath'' in the array + of ''filters'' instead' + type: string + filters: + description: 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. + items: + description: 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. + properties: + event: + description: The definition of the event, either provided + in-line when creating the listener, or extracted from the + referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + type: object + eventPath: + description: When creating a listener from an existing FFI, + this is the pathname of the event on that FFI to be detected + by this listener + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For + example an Ethereum contract address, or a Fabric chaincode + name and channel + type: object + type: array + interface: + description: 'Deprecated: Please use ''interface'' in the array + of ''filters'' instead' + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 'Deprecated: Please use ''location'' in the array of + ''filters'' instead' + name: + description: A descriptive name for the listener + type: string + options: + description: Options that control how the listener subscribes to + events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + topic: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + signature: + description: A concatenation of all the stringified signature + of the event and location, as computed by the blockchain plugin + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/query: + post: + description: Queries a method on a smart contract. Performs a read-only query. + operationId: postContractQueryNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + errors: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + items: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + interface: + description: The UUID of a method within a pre-configured FireFly + interface (FFI) definition for a smart contract. Required if the + 'method' is omitted. Also see Contract APIs as a way to configure + a dedicated API for your FFI, including all methods and an OpenAPI/Swagger + interface + format: uuid + type: string + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + message: + description: You can specify a message to correlate with the invocation, + which can be of type broadcast or private. Your specified method + must support on-chain/off-chain correlation by taking a data input + on the call + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + method: + description: An in-line FFI method definition for the method to + invoke. Required when FFI is not specified + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + methodPath: + description: The pathname of the method on the specified FFI + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + additionalProperties: {} + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data: + get: + description: Gets a list of data items + operationId: getDataNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.path + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.public + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.size + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datatype.name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datatype.version + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: public + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: validator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: value + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + path: + description: If a name is specified, this field stores the + '/' prefixed and separated path extracted from the full + name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the + value and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates a new data item in this FireFly node + operationId: postDataNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + datatype: + description: The optional datatype to use for validation of the + in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON type + - object, array, string, number or boolean + type: object + multipart/form-data: + schema: + properties: + autometa: + description: Success + type: string + datatype.name: + description: Success + type: string + datatype.version: + description: Success + type: string + filename.ext: + format: binary + type: string + metadata: + description: Success + type: string + validator: + description: Success + type: string + type: object + responses: + "201": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + path: + description: If a name is specified, this field stores the + '/' prefixed and separated path extracted from the full + name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data/{dataid}: + delete: + description: Deletes a data item by its ID, including metadata about this item + operationId: deleteDataNamespace + parameters: + - description: The data item ID + in: path + name: dataid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Non-Default Namespace + get: + description: Gets a data item by its ID, including metadata about this item + operationId: getDataByIDNamespace + parameters: + - description: The data item ID + in: path + name: dataid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + path: + description: If a name is specified, this field stores the + '/' prefixed and separated path extracted from the full + name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data/{dataid}/blob: + get: + description: Downloads the original file that was previously uploaded or received + operationId: getDataBlobNamespace + parameters: + - description: The data item ID + in: path + name: dataid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: rejectreason + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + format: byte + type: string + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data/{dataid}/blob/publish: + post: + description: Publishes the binary blob attachment stored in your local data + exchange, to shared storage + operationId: postDataBlobPublishNamespace + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + path: + description: If a name is specified, this field stores the + '/' prefixed and separated path extracted from the full + name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data/{dataid}/messages: + get: + description: Gets a list of the messages associated with a data item + operationId: getDataMsgsNamespace + parameters: + - description: The data item ID + in: path + name: dataid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: rejectreason + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data/{dataid}/value: + get: + description: Downloads the JSON value of the data resource, without the associated + metadata + operationId: getDataValueNamespace + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: rejectreason + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + format: byte + type: string + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data/{dataid}/value/publish: + post: + description: Publishes the JSON value from the specified data resource, to shared + storage + operationId: postDataValuePublishNamespace + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + path: + description: If a name is specified, this field stores the + '/' prefixed and separated path extracted from the full + name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/datasubpaths/{parent}: + get: + description: Gets a list of path names of named blob data, underneath a given + parent path ('/' path prefixes are automatically pre-prepended) + operationId: getDataSubPathsNamespace + parameters: + - description: The parent path to query + in: path + name: parent + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + type: string + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/datatypes: + get: + description: Gets a list of datatypes that have been published + operationId: getDatatypesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: validator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: version + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used + to publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions + can exist with the same name. Use of semantic versioning is + encourages, such as v1.0.1 + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates and broadcasts a new datatype + operationId: postNewDatatypeNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + name: + description: The name of the datatype + type: string + validator: + description: The validator that should be used to verify this datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/datatypes/{name}/{version}: + get: + description: Gets a datatype by its name and version + operationId: getDatatypeByNameNamespace + parameters: + - description: The name of the datatype + in: path + name: name + required: true + schema: + type: string + - description: The version of the datatype + in: path + name: version + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/events: + get: + description: Gets a list of events + operationId: getEventsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the record that this item references + in its 'reference' field + in: query + name: fetchreferences + schema: + example: "true" + type: string + - description: When set, the API will return the record that this item references + in its 'reference' field + in: query + name: fetchreference + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: correlator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: reference + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part + of. Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/events/{eid}: + get: + description: Gets an event by its ID + operationId: getEventByIDNamespace + parameters: + - description: The event ID + in: path + name: eid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the record that this item references + in its 'reference' field + in: query + name: fetchreference + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part of. + Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/groups: + get: + description: Gets a list of groups + operationId: getGroupsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: ledger + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time when the group was first used to send + a message in the network + format: date-time + type: string + hash: + description: The identifier hash of this group. Derived from + the name and group members + format: byte + type: string + localNamespace: + description: The local namespace of the group + type: string + members: + description: The list of members in this privacy group + items: + description: The list of members in this privacy group + properties: + identity: + description: The DID of the group member + type: string + node: + description: The UUID of the node that receives a copy + of the off-chain message for the identity + format: uuid + type: string + type: object + type: array + message: + description: The message used to broadcast this group privately + to the members + format: uuid + type: string + name: + description: The optional name of the group, allowing multiple + unique groups to exist with the same list of recipients + type: string + namespace: + description: The namespace of the group within the multiparty + network + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/groups/{hash}: + get: + description: Gets a group by its ID (hash) + operationId: getGroupByHashNamespace + parameters: + - description: The hash of the group + in: path + name: hash + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time when the group was first used to send a + message in the network + format: date-time + type: string + hash: + description: The identifier hash of this group. Derived from the + name and group members + format: byte + type: string + localNamespace: + description: The local namespace of the group + type: string + members: + description: The list of members in this privacy group + items: + description: The list of members in this privacy group + properties: + identity: + description: The DID of the group member + type: string + node: + description: The UUID of the node that receives a copy of + the off-chain message for the identity + format: uuid + type: string + type: object + type: array + message: + description: The message used to broadcast this group privately + to the members + format: uuid + type: string + name: + description: The optional name of the group, allowing multiple + unique groups to exist with the same list of recipients + type: string + namespace: + description: The namespace of the group within the multiparty + network + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/identities: + get: + description: Gets a list of all identities that have been registered in the + namespace + operationId: getIdentitiesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to + prove data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum + address, or Fabric MSP identifier + type: string + type: object + type: array + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Registers a new identity in the network + operationId: postNewIdentityNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + key: + description: The blockchain signing key to use to make the claim + to the identity. Must be available to the local node to sign the + identity claim. Will become a verifier on the established identity + type: string + name: + description: The name of the identity. The name must be unique within + the type and namespace + type: string + parent: + description: On input the parent can be specified directly as the + UUID of and existing identity, or as a DID to resolve to that + identity, or an organization name. The parent must already have + been registered, and its blockchain signing key must be available + to the local node to sign the verification + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/identities/{did}: + get: + description: Gets an identity by its ID + operationId: getIdentityByIDNamespace + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + example: id + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + patch: + description: Updates an identity + operationId: patchUpdateIdentityNamespace + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/identities/{iid}/did: + get: + description: Gets the DID for an identity based on its ID + operationId: getIdentityDIDNamespace + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + example: id + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + '@context': + description: See https://www.w3.org/TR/did-core/#json-ld + items: + description: See https://www.w3.org/TR/did-core/#json-ld + type: string + type: array + authentication: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + type: array + id: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + verificationMethod: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + properties: + blockchainAcountId: + description: For blockchains like Ethereum that represent + signing identities directly by their public key summarized + in an account string + type: string + controller: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + dataExchangePeerID: + description: A string provided by your Data Exchange plugin, + that it uses a technology specific mechanism to validate + against when messages arrive from this identity + type: string + id: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + mspIdentityString: + description: For Hyperledger Fabric where the signing identity + is represented by an MSP identifier (containing X509 certificate + DN strings) that were validated by your local MSP + type: string + type: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/identities/{iid}/verifiers: + get: + description: Gets the verifiers for an identity + operationId: getIdentityVerifiersNamespace + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + example: id + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: identity + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: value + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time this verifier was created on this node + format: date-time + type: string + hash: + description: Hash used as a globally consistent identifier for + this namespace + type + value combination on every node in + the network + format: byte + type: string + identity: + description: The UUID of the parent identity that has claimed + this verifier + format: uuid + type: string + namespace: + description: The namespace of the verifier + type: string + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages: + get: + description: Gets a list of messages + operationId: getMsgsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Fetch the data and include it in the messages returned + in: query + name: fetchdata + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: rejectreason + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txparent.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + batch: + description: The UUID of the batch in which the message was + pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the + message. Derived from the array of data ids+hashes attached + to this message + format: byte + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce + is assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on + the rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver + this message + format: uuid + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/{msgid}: + get: + description: Gets a message by its ID + operationId: getMsgByIDNamespace + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Fetch the data and include it in the messages returned + in: query + name: fetchdata + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + properties: + blob: + description: An optional in-line hash reference to a previously + uploaded binary data blob + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached + to the blob, commonly used as a path/filename, and + indexed for search + type: string + path: + description: If a name is specified, this field stores + the '/' prefixed and separated path extracted from + the full name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will be + picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/{msgid}/data: + get: + description: Gets the list of data items that are attached to a message + operationId: getMsgDataNamespace + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + path: + description: If a name is specified, this field stores the + '/' prefixed and separated path extracted from the full + name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the + value and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/{msgid}/events: + get: + description: Gets the list of events for a message + operationId: getMsgEventsNamespace + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: correlator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: reference + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part + of. Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/{msgid}/transaction: + get: + description: Gets the transaction for a message + operationId: getMsgTxnNamespace + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + blockchainIds: + description: 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 + items: + description: 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 + type: string + type: array + created: + description: 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 + format: date-time + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + idempotencyKey: + description: An optional unique identifier for a transaction. + Cannot be duplicated within a namespace, thus allowing idempotent + submission of transactions to the API + type: string + namespace: + description: The namespace of the FireFly transaction + type: string + type: + description: The type of the FireFly transaction + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/broadcast: + post: + description: Broadcasts a message to all members in the network + operationId: postNewMessageBroadcastNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation of + the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON + type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive a + copy of the off-chain message for the identity. The + first applicable node for the identity will be picked + automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list of + the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the message + to the applications that process it + type: string + topics: + description: A message topic associates this message with an + ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver this + message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/private: + post: + description: Privately sends a message to one or more members in the network + operationId: postNewMessagePrivateNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation of + the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON + type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive a + copy of the off-chain message for the identity. The + first applicable node for the identity will be picked + automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list of + the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the message + to the applications that process it + type: string + topics: + description: A message topic associates this message with an + ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver this + message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/requestreply: + post: + description: Sends a message with a blocking HTTP request, waits for a reply + to that message, then sends the reply as the HTTP response. + operationId: postNewMessageRequestReplyNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation of + the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON + type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive a + copy of the off-chain message for the identity. The + first applicable node for the identity will be picked + automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list of + the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the message + to the applications that process it + type: string + topics: + description: A message topic associates this message with an + ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver this + message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + properties: + blob: + description: An optional in-line hash reference to a previously + uploaded binary data blob + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached + to the blob, commonly used as a path/filename, and + indexed for search + type: string + path: + description: If a name is specified, this field stores + the '/' prefixed and separated path extracted from + the full name + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will be + picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txparent: + description: The parent transaction that originally triggered + this message + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + rejectReason: + description: If a message was rejected, provides details on the + rejection reason + type: string + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + - cancelled + type: string + txid: + description: The ID of the transaction used to order/deliver this + message + format: uuid + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/action: + post: + description: Notify all nodes in the network of a new governance action + operationId: postNetworkActionNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + type: + description: The action to be performed + enum: + - terminate + type: string + type: object + responses: + "202": + content: + application/json: + schema: + properties: + type: + description: The action to be performed + enum: + - terminate + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/diddocs/{did}: + get: + description: Gets a DID document by its DID + operationId: getNetworkDIDDocByDIDNamespace + parameters: + - description: The identity DID + in: path + name: did + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + '@context': + description: See https://www.w3.org/TR/did-core/#json-ld + items: + description: See https://www.w3.org/TR/did-core/#json-ld + type: string + type: array + authentication: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + type: array + id: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + verificationMethod: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + properties: + blockchainAcountId: + description: For blockchains like Ethereum that represent + signing identities directly by their public key summarized + in an account string + type: string + controller: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + dataExchangePeerID: + description: A string provided by your Data Exchange plugin, + that it uses a technology specific mechanism to validate + against when messages arrive from this identity + type: string + id: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + mspIdentityString: + description: For Hyperledger Fabric where the signing identity + is represented by an MSP identifier (containing X509 certificate + DN strings) that were validated by your local MSP + type: string + type: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/identities: + get: + deprecated: true + description: Gets the list of identities in the network (deprecated - use /identities + instead of /network/identities + operationId: getNetworkIdentitiesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to + prove data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum + address, or Fabric MSP identifier + type: string + type: object + type: array + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/identities/{did}: + get: + deprecated: true + description: Gets an identity by its DID + operationId: getNetworkIdentityByDIDNamespace + parameters: + - description: The identity DID + in: path + name: did + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, that + have been bound to this identity and can be used to prove data + orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/nodes: + get: + description: Gets a list of nodes in the network + operationId: getNetworkNodesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/nodes/{nameOrId}: + get: + description: Gets information about a specific node in the network + operationId: getNetworkNodeNamespace + parameters: + - description: The name or ID of the node + in: path + name: nameOrId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/nodes/self: + post: + description: Instructs this FireFly node to register itself on the network + operationId: postNodesSelfNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + additionalProperties: {} + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/organizations: + get: + description: Gets a list of orgs in the network + operationId: getNetworkOrgsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Registers a new org in the network + operationId: postNewOrganizationNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + key: + description: The blockchain signing key to use to make the claim + to the identity. Must be available to the local node to sign the + identity claim. Will become a verifier on the established identity + type: string + name: + description: The name of the identity. The name must be unique within + the type and namespace + type: string + parent: + description: On input the parent can be specified directly as the + UUID of and existing identity, or as a DID to resolve to that + identity, or an organization name. The parent must already have + been registered, and its blockchain signing key must be available + to the local node to sign the verification + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/organizations/{nameOrId}: + get: + description: Gets information about a specific org in the network + operationId: getNetworkOrgNamespace + parameters: + - description: The name or ID of the org + in: path + name: nameOrId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/organizations/self: + post: + description: Instructs this FireFly node to register its org on the network + operationId: postNewOrganizationSelfNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + additionalProperties: {} + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/nextpins: + get: + description: Queries the list of next-pins that determine the next masked message + sequence for each member of a privacy group, on each context/topic + operationId: getNextPinsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: context + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: identity + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: nonce + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + context: + description: 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 + format: byte + type: string + hash: + description: The unique masked pin string + format: byte + type: string + identity: + description: The member of the privacy group the next-pin applies + to + type: string + namespace: + description: The namespace of the next-pin + type: string + nonce: + description: The numeric index - which is monotonically increasing + for each member of the privacy group + format: int64 + type: integer + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/operations: + get: + description: Gets a a list of operations + operationId: getOpsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: error + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: input + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: output + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: plugin + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: retry + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: status + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for + this operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a + previous operation, this field points to the UUID of the operation + being retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/operations/{opid}: + get: + description: Gets an operation by ID + operationId: getOpByIDNamespace + parameters: + - description: The operation ID key to get + in: path + name: opid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return additional status information if + available + in: query + name: fetchstatus + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + detail: + description: Additional detailed information about an operation + provided by the connector + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/operations/{opid}/retry: + post: + description: Retries a failed operation + operationId: postOpRetryNamespace + parameters: + - description: The UUID of the operation + in: path + name: opid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + additionalProperties: {} + type: object + responses: + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/pins: + get: + description: Queries the list of pins received from the blockchain + operationId: getPinsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: dispatched + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: index + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: masked + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + batch: + description: The UUID of the batch of messages this pin is part + of + format: uuid + type: string + batchHash: + description: The manifest hash batch of messages this pin is + part of + format: byte + type: string + created: + description: The time the FireFly node created the pin + format: date-time + type: string + dispatched: + description: Once true, this pin has been processed and will + not be processed again + type: boolean + hash: + description: The hash represents a topic within a message in + the batch. If a message has multiple topics, then multiple + pins are created. If the message is private, the hash is masked + for privacy + format: byte + type: string + index: + description: The index of this pin within the batch. One pin + is created for each topic, of each message in the batch + format: int64 + type: integer + masked: + description: True if the pin is for a private message, and hence + is masked with the group ID and salted with a nonce so observers + of the blockchain cannot use pin hash to match this transaction + to other transactions or participants + type: boolean + namespace: + description: The namespace of the pin + type: string + sequence: + description: The order of the pin in the local FireFly database, + which matches the order in which pins were delivered to FireFly + by the blockchain connector event stream + format: int64 + type: integer + signer: + description: The blockchain signing key that submitted this + transaction, as passed through to FireFly by the smart contract + that emitted the blockchain event + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/pins/rewind: + post: + description: Force a rewind of the event aggregator to a previous position, + to re-evaluate (and possibly dispatch) that pin and others after it. Only + accepts a sequence or batch ID for a currently undispatched pin + operationId: postPinsRewindNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + batch: + description: The ID of the batch to which the event aggregator should + rewind. Either sequence or batch must be specified + format: uuid + type: string + sequence: + description: The sequence of the pin to which the event aggregator + should rewind. Either sequence or batch must be specified + format: int64 + type: integer + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The ID of the batch to which the event aggregator + should rewind. Either sequence or batch must be specified + format: uuid + type: string + sequence: + description: The sequence of the pin to which the event aggregator + should rewind. Either sequence or batch must be specified + format: int64 + type: integer + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/status: + get: + description: Gets the status of this namespace + operationId: getStatusNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + multiparty: + description: Information about the multi-party system configured + on this namespace + properties: + contract: + description: Information about the multi-party smart contract + configured for this namespace + properties: + active: + description: The currently active FireFly smart contract + properties: + firstEvent: + description: 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 + type: string + index: + description: The index of this contract in the config + file + type: integer + info: + description: Additional info about the current status + of the multi-party contract + properties: + finalEvent: + description: The identifier for the final blockchain + event received from this contract before termination + type: string + subscription: + description: The backend identifier of the subscription + for the FireFly BatchPin contract + type: string + version: + description: The version of this multiparty contract + type: integer + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + type: object + terminated: + description: Previously-terminated FireFly smart contracts + items: + description: Previously-terminated FireFly smart contracts + properties: + firstEvent: + description: 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 + type: string + index: + description: The index of this contract in the config + file + type: integer + info: + description: Additional info about the current status + of the multi-party contract + properties: + finalEvent: + description: The identifier for the final blockchain + event received from this contract before termination + type: string + subscription: + description: The backend identifier of the subscription + for the FireFly BatchPin contract + type: string + version: + description: The version of this multiparty + contract + type: integer + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a + Fabric chaincode name and channel + type: object + type: array + type: object + enabled: + description: Whether multi-party mode is enabled for this + namespace + type: boolean + type: object + namespace: + description: The namespace that this status applies to + properties: + created: + description: The time the namespace was created + format: date-time + type: string + description: + description: A description of the namespace + type: string + name: + description: The local namespace name + type: string + networkName: + description: The shared namespace name within the multiparty + network + type: string + type: object + node: + description: Details of the local node + properties: + id: + description: The UUID of the node, if registered + format: uuid + type: string + name: + description: The name of this node, as specified in the local + configuration + type: string + registered: + description: Whether the node has been successfully registered + type: boolean + type: object + org: + description: Details of the root organization identity registered + for this namespace on the local node + properties: + did: + description: The DID of the organization identity, if registered + type: string + id: + description: The UUID of the organization, if registered + format: uuid + type: string + name: + description: The name of the node operator organization, as + specified in the local configuration + type: string + registered: + description: Whether the organization has been successfully + registered + type: boolean + verifiers: + description: Array of verifiers (blockchain keys) owned by + this identity + items: + description: Array of verifiers (blockchain keys) owned + by this identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum + address, or Fabric MSP identifier + type: string + type: object + type: array + type: object + plugins: + description: Information about plugins configured on this namespace + properties: + blockchain: + description: The blockchain plugins on this namespace + items: + description: The blockchain plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + dataExchange: + description: The data exchange plugins on this namespace + items: + description: The data exchange plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + database: + description: The database plugins on this namespace + items: + description: The database plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + events: + description: The event plugins on this namespace + items: + description: The event plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + identity: + description: The identity plugins on this namespace + items: + description: The identity plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + sharedStorage: + description: The shared storage plugins on this namespace + items: + description: The shared storage plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + tokens: + description: The token plugins on this namespace + items: + description: The token plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + type: object + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/status/batchmanager: + get: + description: Gets the status of the batch manager + operationId: getStatusBatchManagerNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + processors: + description: An array of currently active batch processors + items: + description: An array of currently active batch processors + properties: + dispatcher: + description: The type of dispatcher for this processor + type: string + name: + description: The name of the processor, which includes details + of the attributes of message are allocated to this processor + type: string + status: + description: The flush status for this batch processor + properties: + averageBatchBytes: + description: The average byte size of each batch + format: int64 + type: integer + averageBatchData: + description: The average number of data attachments + included in each batch + format: double + type: number + averageBatchMessages: + description: The average number of messages included + in each batch + format: double + type: number + averageFlushTimeMS: + description: The average amount of time spent flushing + each batch + format: int64 + type: integer + blocked: + description: True if the batch flush is in a retry loop, + due to errors being returned by the plugins + type: boolean + cancelled: + description: True if the current batch flush has been + cancelled + type: boolean + flushing: + description: If a flush is in progress, this is the + UUID of the batch being flushed + format: uuid + type: string + lastFlushError: + description: The last error received by this batch processor + while flushing + type: string + lastFlushErrorTime: + description: The time of the last flush + format: date-time + type: string + lastFlushStartTime: + description: The last time a flush was performed + format: date-time + type: string + totalBatches: + description: The total count of batches flushed by this + processor since it started + format: int64 + type: integer + totalErrors: + description: The total count of error flushed encountered + by this processor since it started + format: int64 + type: integer + type: object + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/status/multiparty: + get: + description: Gets the registration status of this organization and node on the + configured multiparty network + operationId: getStatusMultipartyNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + contracts: + description: Information about the active and terminated multi-party + smart contracts configured for this namespace + properties: + active: + description: The currently active FireFly smart contract + properties: + firstEvent: + description: 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 + type: string + index: + description: The index of this contract in the config + file + type: integer + info: + description: Additional info about the current status + of the multi-party contract + properties: + finalEvent: + description: The identifier for the final blockchain + event received from this contract before termination + type: string + subscription: + description: The backend identifier of the subscription + for the FireFly BatchPin contract + type: string + version: + description: The version of this multiparty contract + type: integer + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + status: + description: The status of the contract listener. One + of 'syncing', 'synced', or 'unknown' + type: string + type: object + terminated: + description: Previously-terminated FireFly smart contracts + items: + description: Previously-terminated FireFly smart contracts + properties: + firstEvent: + description: 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 + type: string + index: + description: The index of this contract in the config + file + type: integer + info: + description: Additional info about the current status + of the multi-party contract + properties: + finalEvent: + description: The identifier for the final blockchain + event received from this contract before termination + type: string + subscription: + description: The backend identifier of the subscription + for the FireFly BatchPin contract + type: string + version: + description: The version of this multiparty contract + type: integer + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + type: object + type: array + type: object + enabled: + description: Whether multi-party mode is enabled for this namespace + type: boolean + node: + description: Details of the local node + properties: + pendingRegistrationMessageId: + description: The ID of the pending message that broadcast + the identity claim to the network + format: uuid + type: string + status: + description: The status of the node registration, one of 'unregistered', + 'registering', 'registered', and 'unknown' + type: string + type: object + org: + description: Details of the root organization identity registered + for this namespace on the local node + properties: + pendingRegistrationMessageId: + description: The ID of the pending message that broadcast + the identity claim to the network + format: uuid + type: string + status: + description: The status of the organization registration, + one of 'unregistered', 'registering', 'registered', and + 'unknown' + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/subscriptions: + get: + description: Gets a list of subscriptions + operationId: getSubscriptionsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: events + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: filters + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: options + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: transport + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' + instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event + in the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this + filter is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the + subscription + type: string + options: + description: Subscription options + properties: + batch: + description: 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. + type: boolean + batchTimeout: + description: When batching is enabled, the optional timeout + to send events even when the batch hasn't filled. + type: string + fastack: + description: 'Webhooks only: When true the event will be + acknowledged before the webhook is invoked, allowing parallel + invocations' + type: boolean + firstEvent: + description: 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on + the webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + httpOptions: + description: 'Webhooks only: a set of options for HTTP' + properties: + connectionTimeout: + description: The maximum amount of time that a connection + is allowed to remain with no data transmitted. + type: string + expectContinueTimeout: + description: See [ExpectContinueTimeout in the Go docs](https://pkg.go.dev/net/http#Transport) + type: string + idleTimeout: + description: The max duration to hold a HTTP keepalive + connection between calls + type: string + maxIdleConns: + description: The max number of idle connections to hold + pooled + type: integer + proxyURL: + description: HTTP proxy URL to use for outbound requests + to the webhook + type: string + requestTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + tlsHandshakeTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + type: object + input: + description: 'Webhooks only: A set of options to extract + data from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data + input, to use for the request body. Default is the + whole first body + type: string + headers: + description: A top-level property of the first data + input, to use for headers + type: string + path: + description: A top-level property of the first data + input, to use for a path to append with escaping to + the webhook path + type: string + query: + description: A top-level property of the first data + input, to use for query parameters + type: string + replytx: + description: A top-level property of the first data + input, to use to dynamically set whether to pin the + response (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set + on the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply + message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set + on the reply message' + type: string + retry: + description: 'Webhooks only: a set of options for retrying + the webhook call' + properties: + count: + description: Number of times to retry the webhook call + in case of failure + type: integer + enabled: + description: Enables retry on HTTP calls, defaults to + false + type: boolean + initialDelay: + description: Initial delay between retries when we retry + the webhook call + type: string + maxDelay: + description: Max delay between retries when we retry + the webhookcall + type: string + type: object + tlsConfigName: + description: The name of an existing TLS configuration associated + to the namespace to use + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be + relative if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates a new subscription for an application to receive events + from FireFly + operationId: postNewSubscriptionNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an event + is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription will + only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + batch: + description: 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. + type: boolean + batchTimeout: + description: When batching is enabled, the optional timeout + to send events even when the batch hasn't filled. + type: string + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the webhook + request' + type: object + httpOptions: + description: 'Webhooks only: a set of options for HTTP' + properties: + connectionTimeout: + description: The maximum amount of time that a connection + is allowed to remain with no data transmitted. + type: string + expectContinueTimeout: + description: See [ExpectContinueTimeout in the Go docs](https://pkg.go.dev/net/http#Transport) + type: string + idleTimeout: + description: The max duration to hold a HTTP keepalive connection + between calls + type: string + maxIdleConns: + description: The max number of idle connections to hold + pooled + type: integer + proxyURL: + description: HTTP proxy URL to use for outbound requests + to the webhook + type: string + requestTimeout: + description: The max duration to hold a TLS handshake alive + type: string + tlsHandshakeTimeout: + description: The max duration to hold a TLS handshake alive + type: string + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. Only + applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set on + the webhook request' + type: string + description: 'Webhooks only: Static query params to set on the + webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send a + reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + retry: + description: 'Webhooks only: a set of options for retrying the + webhook call' + properties: + count: + description: Number of times to retry the webhook call in + case of failure + type: integer + enabled: + description: Enables retry on HTTP calls, defaults to false + type: boolean + initialDelay: + description: Initial delay between retries when we retry + the webhook call + type: string + maxDelay: + description: Max delay between retries when we retry the + webhookcall + type: string + type: object + tlsConfigName: + description: The name of an existing TLS configuration associated + to the namespace to use + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + type: object + responses: + "201": + content: + application/json: + schema: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + batch: + description: 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. + type: boolean + batchTimeout: + description: When batching is enabled, the optional timeout + to send events even when the batch hasn't filled. + type: string + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + httpOptions: + description: 'Webhooks only: a set of options for HTTP' + properties: + connectionTimeout: + description: The maximum amount of time that a connection + is allowed to remain with no data transmitted. + type: string + expectContinueTimeout: + description: See [ExpectContinueTimeout in the Go docs](https://pkg.go.dev/net/http#Transport) + type: string + idleTimeout: + description: The max duration to hold a HTTP keepalive + connection between calls + type: string + maxIdleConns: + description: The max number of idle connections to hold + pooled + type: integer + proxyURL: + description: HTTP proxy URL to use for outbound requests + to the webhook + type: string + requestTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + tlsHandshakeTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set on + the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + retry: + description: 'Webhooks only: a set of options for retrying + the webhook call' + properties: + count: + description: Number of times to retry the webhook call + in case of failure + type: integer + enabled: + description: Enables retry on HTTP calls, defaults to + false + type: boolean + initialDelay: + description: Initial delay between retries when we retry + the webhook call + type: string + maxDelay: + description: Max delay between retries when we retry the + webhookcall + type: string + type: object + tlsConfigName: + description: The name of an existing TLS configuration associated + to the namespace to use + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + put: + description: Update an existing subscription + operationId: putSubscriptionNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an event + is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription will + only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + batch: + description: 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. + type: boolean + batchTimeout: + description: When batching is enabled, the optional timeout + to send events even when the batch hasn't filled. + type: string + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the webhook + request' + type: object + httpOptions: + description: 'Webhooks only: a set of options for HTTP' + properties: + connectionTimeout: + description: The maximum amount of time that a connection + is allowed to remain with no data transmitted. + type: string + expectContinueTimeout: + description: See [ExpectContinueTimeout in the Go docs](https://pkg.go.dev/net/http#Transport) + type: string + idleTimeout: + description: The max duration to hold a HTTP keepalive connection + between calls + type: string + maxIdleConns: + description: The max number of idle connections to hold + pooled + type: integer + proxyURL: + description: HTTP proxy URL to use for outbound requests + to the webhook + type: string + requestTimeout: + description: The max duration to hold a TLS handshake alive + type: string + tlsHandshakeTimeout: + description: The max duration to hold a TLS handshake alive + type: string + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. Only + applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set on + the webhook request' + type: string + description: 'Webhooks only: Static query params to set on the + webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send a + reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + retry: + description: 'Webhooks only: a set of options for retrying the + webhook call' + properties: + count: + description: Number of times to retry the webhook call in + case of failure + type: integer + enabled: + description: Enables retry on HTTP calls, defaults to false + type: boolean + initialDelay: + description: Initial delay between retries when we retry + the webhook call + type: string + maxDelay: + description: Max delay between retries when we retry the + webhookcall + type: string + type: object + tlsConfigName: + description: The name of an existing TLS configuration associated + to the namespace to use + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + batch: + description: 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. + type: boolean + batchTimeout: + description: When batching is enabled, the optional timeout + to send events even when the batch hasn't filled. + type: string + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + httpOptions: + description: 'Webhooks only: a set of options for HTTP' + properties: + connectionTimeout: + description: The maximum amount of time that a connection + is allowed to remain with no data transmitted. + type: string + expectContinueTimeout: + description: See [ExpectContinueTimeout in the Go docs](https://pkg.go.dev/net/http#Transport) + type: string + idleTimeout: + description: The max duration to hold a HTTP keepalive + connection between calls + type: string + maxIdleConns: + description: The max number of idle connections to hold + pooled + type: integer + proxyURL: + description: HTTP proxy URL to use for outbound requests + to the webhook + type: string + requestTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + tlsHandshakeTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set on + the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + retry: + description: 'Webhooks only: a set of options for retrying + the webhook call' + properties: + count: + description: Number of times to retry the webhook call + in case of failure + type: integer + enabled: + description: Enables retry on HTTP calls, defaults to + false + type: boolean + initialDelay: + description: Initial delay between retries when we retry + the webhook call + type: string + maxDelay: + description: Max delay between retries when we retry the + webhookcall + type: string + type: object + tlsConfigName: + description: The name of an existing TLS configuration associated + to the namespace to use + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/subscriptions/{subid}: + delete: + description: Deletes a subscription + operationId: deleteSubscriptionNamespace + parameters: + - description: The subscription ID + in: path + name: subid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Non-Default Namespace + get: + description: Gets a subscription by its ID + operationId: getSubscriptionByIDNamespace + parameters: + - description: The subscription ID + in: path + name: subid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return additional status information if + available + in: query + name: fetchstatus + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + batch: + description: 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. + type: boolean + batchTimeout: + description: When batching is enabled, the optional timeout + to send events even when the batch hasn't filled. + type: string + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + httpOptions: + description: 'Webhooks only: a set of options for HTTP' + properties: + connectionTimeout: + description: The maximum amount of time that a connection + is allowed to remain with no data transmitted. + type: string + expectContinueTimeout: + description: See [ExpectContinueTimeout in the Go docs](https://pkg.go.dev/net/http#Transport) + type: string + idleTimeout: + description: The max duration to hold a HTTP keepalive + connection between calls + type: string + maxIdleConns: + description: The max number of idle connections to hold + pooled + type: integer + proxyURL: + description: HTTP proxy URL to use for outbound requests + to the webhook + type: string + requestTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + tlsHandshakeTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set on + the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + retry: + description: 'Webhooks only: a set of options for retrying + the webhook call' + properties: + count: + description: Number of times to retry the webhook call + in case of failure + type: integer + enabled: + description: Enables retry on HTTP calls, defaults to + false + type: boolean + initialDelay: + description: Initial delay between retries when we retry + the webhook call + type: string + maxDelay: + description: Max delay between retries when we retry the + webhookcall + type: string + type: object + tlsConfigName: + description: The name of an existing TLS configuration associated + to the namespace to use + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/subscriptions/{subid}/events: + get: + description: Gets a collection of events filtered by the subscription for further + filtering + operationId: getSubscriptionEventsFilteredNamespace + parameters: + - description: The subscription ID + in: path + name: subid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: The sequence ID in the raw event stream to start indexing through + events from. Leave blank to start indexing from the most recent events + in: query + name: startsequence + schema: + type: string + - description: The sequence ID in the raw event stream to stop indexing through + events at. Leave blank to start indexing from the most recent events + in: query + name: endsequence + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: correlator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: reference + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part + of. Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/accounts: + get: + description: Gets a list of token accounts + operationId: getTokenAccountsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + key: + description: The blockchain signing identity this balance applies + to + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/accounts/{key}/pools: + get: + description: Gets a list of token pools that contain a given token account key + operationId: getTokenAccountPoolsNamespace + parameters: + - description: The key for the token account. The exact format may vary based + on the token connector use + in: path + name: key + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + pool: + description: The UUID the token pool this balance entry applies + to + format: uuid + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/approvals: + get: + description: Gets a list of token approvals + operationId: getTokenApprovalsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: active + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: approved + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainevent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: localid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messagehash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: operator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: protocolid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: subject + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + active: + description: Indicates if this approval is currently active + (only one approval can be active per subject) + type: boolean + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes + permission (false) + type: boolean + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the token approval + format: date-time + type: string + info: + additionalProperties: + description: 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 + description: 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 + type: object + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token approval, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated + with this approval using the data field of the approval in + a compatible token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated + with this approval using the data field of the approval in + a compatible token connector + format: byte + type: string + namespace: + description: The namespace for the approval, which must match + the namespace of the token pool + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + subject: + description: A string identifying the parties and entities in + the scope of this approval, as provided by the token connector + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in + use supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates a token approval + operationId: postTokenApprovalNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes permission + (false) + type: boolean + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the approval. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the approval. See your chosen token connector documentation + for details + type: object + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + message: + description: You can specify a message to correlate with the approval, + which can be of type broadcast or private. Your chosen token connector + and on-chain smart contract must support on-chain/off-chain correlation + by taking a `data` input on the approval + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + active: + description: Indicates if this approval is currently active (only + one approval can be active per subject) + type: boolean + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes permission + (false) + type: boolean + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the token approval + format: date-time + type: string + info: + additionalProperties: + description: 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 + description: 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 + type: object + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token approval, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the approval, which must match + the namespace of the token pool + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + subject: + description: A string identifying the parties and entities in + the scope of this approval, as provided by the token connector + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + active: + description: Indicates if this approval is currently active (only + one approval can be active per subject) + type: boolean + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes permission + (false) + type: boolean + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the token approval + format: date-time + type: string + info: + additionalProperties: + description: 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 + description: 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 + type: object + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token approval, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the approval, which must match + the namespace of the token pool + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + subject: + description: A string identifying the parties and entities in + the scope of this approval, as provided by the token connector + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/balances: + get: + description: Gets a list of token balances + operationId: getTokenBalancesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: balance + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tokenindex + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: uri + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + balance: + description: The numeric balance. For non-fungible tokens will + always be 1. For fungible tokens, the number of decimals for + the token pool should be considered when interpreting the + balance. For example, with 18 decimals a fractional balance + of 10.234 will be returned as 10,234,000,000,000,000,000 + type: string + connector: + description: The token connector that is responsible for the + token pool of this balance entry + type: string + key: + description: The blockchain signing identity this balance applies + to + type: string + namespace: + description: The namespace of the token pool for this balance + entry + type: string + pool: + description: The UUID the token pool this balance entry applies + to + format: uuid + type: string + tokenIndex: + description: The index of the token within the pool that this + balance applies to + type: string + updated: + description: The last time the balance was updated by applying + a transfer event + format: date-time + type: string + uri: + description: The URI of the token this balance entry applies + to + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/burn: + post: + description: Burns some tokens + operationId: postTokenBurnNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + type: object + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + message: + description: You can specify a message to correlate with the transfer, + which can be of type broadcast or private. Your chosen token connector + and on-chain smart contract must support on-chain/off-chain correlation + by taking a `data` input on the transfer + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + pool: + description: The name or UUID of a token pool + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this transfer + applies to + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/connectors: + get: + description: Gets the list of token connectors currently in use + operationId: getTokenConnectorsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + name: + description: The name of the token connector, as configured + in the FireFly core configuration file + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/mint: + post: + description: Mints some tokens + operationId: postTokenMintNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + type: object + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + message: + description: You can specify a message to correlate with the transfer, + which can be of type broadcast or private. Your chosen token connector + and on-chain smart contract must support on-chain/off-chain correlation + by taking a `data` input on the transfer + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + pool: + description: The name or UUID of a token pool + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this transfer + applies to + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/pools: + get: + description: Gets a list of token pools + operationId: getTokenPoolsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: active + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: decimals + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interfaceformat + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: locator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: networkname + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: published + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: standard + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: symbol + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + active: + description: Indicates whether the pool has been successfully + activated with the token connector + type: boolean + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for + details + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + interfaceFormat: + description: The interface encoding format supported by the + connector for this token pool + enum: + - abi + - ffi + type: string + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network about this pool + format: uuid + type: string + methods: + description: The method definitions resolved by the token connector + to be used by each token operation + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + networkName: + description: The published name of the token pool within the + multiparty network + type: string + published: + description: Indicates if the token pool is published to other + members of the multiparty network + type: boolean + standard: + description: The ERC standard the token pool conforms to, as + reported by the token connector + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates a new token pool + operationId: postTokenPoolNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: When true the definition will be published to all other members + of the multiparty network + in: query + name: publish + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + config: + additionalProperties: + description: 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 + description: 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 + type: object + connector: + description: 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 + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + key: + description: 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 + type: string + name: + description: The name of the token pool. Note the name is not validated + against the description of the token on the blockchain + type: string + networkName: + description: The published name of the token pool within the multiparty + network + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + active: + description: Indicates whether the pool has been successfully + activated with the token connector + type: boolean + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + interfaceFormat: + description: The interface encoding format supported by the connector + for this token pool + enum: + - abi + - ffi + type: string + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network about this pool + format: uuid + type: string + methods: + description: The method definitions resolved by the token connector + to be used by each token operation + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + networkName: + description: The published name of the token pool within the multiparty + network + type: string + published: + description: Indicates if the token pool is published to other + members of the multiparty network + type: boolean + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + active: + description: Indicates whether the pool has been successfully + activated with the token connector + type: boolean + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + interfaceFormat: + description: The interface encoding format supported by the connector + for this token pool + enum: + - abi + - ffi + type: string + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network about this pool + format: uuid + type: string + methods: + description: The method definitions resolved by the token connector + to be used by each token operation + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + networkName: + description: The published name of the token pool within the multiparty + network + type: string + published: + description: Indicates if the token pool is published to other + members of the multiparty network + type: boolean + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/pools/{nameOrId}: + delete: + description: Delete a token pool + operationId: deleteTokenPoolNamespace + parameters: + - description: The token pool name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Non-Default Namespace + get: + description: Gets a token pool by its name or its ID + operationId: getTokenPoolByNameOrIDNamespace + parameters: + - description: The token pool name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + active: + description: Indicates whether the pool has been successfully + activated with the token connector + type: boolean + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + interfaceFormat: + description: The interface encoding format supported by the connector + for this token pool + enum: + - abi + - ffi + type: string + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network about this pool + format: uuid + type: string + methods: + description: The method definitions resolved by the token connector + to be used by each token operation + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + networkName: + description: The published name of the token pool within the multiparty + network + type: string + published: + description: Indicates if the token pool is published to other + members of the multiparty network + type: boolean + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/pools/{nameOrId}/publish: + post: + description: Publish a token pool to all other members of the multiparty network + operationId: postTokenPoolPublishNamespace + parameters: + - description: The token pool name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + networkName: + description: An optional name to be used for publishing this definition + to the multiparty network, which may differ from the local name + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + active: + description: Indicates whether the pool has been successfully + activated with the token connector + type: boolean + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + interfaceFormat: + description: The interface encoding format supported by the connector + for this token pool + enum: + - abi + - ffi + type: string + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network about this pool + format: uuid + type: string + methods: + description: The method definitions resolved by the token connector + to be used by each token operation + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + networkName: + description: The published name of the token pool within the multiparty + network + type: string + published: + description: Indicates if the token pool is published to other + members of the multiparty network + type: boolean + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + active: + description: Indicates whether the pool has been successfully + activated with the token connector + type: boolean + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + interfaceFormat: + description: The interface encoding format supported by the connector + for this token pool + enum: + - abi + - ffi + type: string + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network about this pool + format: uuid + type: string + methods: + description: The method definitions resolved by the token connector + to be used by each token operation + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + networkName: + description: The published name of the token pool within the multiparty + network + type: string + published: + description: Indicates if the token pool is published to other + members of the multiparty network + type: boolean + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/transfers: + get: + description: Gets a list of token transfers + operationId: getTokenTransfersNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: The sending or receiving token account for a token transfer + in: query + name: fromOrTo + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: amount + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainevent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: from + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: localid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messagehash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: protocolid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: to + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tokenindex + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: uri + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On + input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated + with this transfer using the data field of the transfer in + a compatible token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated + with this transfer using the data field of the transfer in + a compatible token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in + use supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Transfers some tokens + operationId: postTokenTransferNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + type: object + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + message: + description: You can specify a message to correlate with the transfer, + which can be of type broadcast or private. Your chosen token connector + and on-chain smart contract must support on-chain/off-chain correlation + by taking a `data` input on the transfer + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + pool: + description: The name or UUID of a token pool + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this transfer + applies to + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/transfers/{transferId}: + get: + description: Gets a token transfer by its ID + operationId: getTokenTransferByIDNamespace + parameters: + - description: The token transfer ID + in: path + name: transferId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/transactions: + get: + description: Gets a list of transactions + operationId: getTxnsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainids + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + blockchainIds: + description: 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 + items: + description: 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 + type: string + type: array + created: + description: 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 + format: date-time + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + idempotencyKey: + description: An optional unique identifier for a transaction. + Cannot be duplicated within a namespace, thus allowing idempotent + submission of transactions to the API + type: string + namespace: + description: The namespace of the FireFly transaction + type: string + type: + description: The type of the FireFly transaction + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/transactions/{txnid}: + get: + description: Gets a transaction by its ID + operationId: getTxnByIDNamespace + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainids + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + properties: + blockchainIds: + description: 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 + items: + description: 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 + type: string + type: array + created: + description: 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 + format: date-time + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + idempotencyKey: + description: An optional unique identifier for a transaction. + Cannot be duplicated within a namespace, thus allowing idempotent + submission of transactions to the API + type: string + namespace: + description: The namespace of the FireFly transaction + type: string + type: + description: The type of the FireFly transaction + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/transactions/{txnid}/blockchainevents: + get: + description: Gets a list blockchain events for a specific transaction + operationId: getTxnBlockchainEventsNamespace + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + id: + description: The UUID assigned to the event by FireFly + format: uuid + type: string + info: + additionalProperties: + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + type: object + listener: + description: The UUID of the listener that detected this event, + or nil for built-in events in the system namespace + format: uuid + type: string + name: + description: The name of the event in the blockchain smart contract + type: string + namespace: + description: The namespace of the listener that detected this + blockchain event + type: string + output: + additionalProperties: + description: The data output by the event, parsed to JSON + according to the interface of the smart contract + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + type: object + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely on the blockchain (convention for plugins + is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) + type: string + source: + description: The blockchain plugin or token service that detected + the event + type: string + timestamp: + description: The time allocated to this event by the blockchain. + This is the block timestamp for most blockchain connectors + format: date-time + type: string + tx: + description: 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 + properties: + blockchainId: + description: The blockchain transaction ID, in the format + specific to the blockchain involved in the transaction. + Not all FireFly transactions include a blockchain + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/transactions/{txnid}/operations: + get: + description: Gets a list of operations in a specific transaction + operationId: getTxnOpsNamespace + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for + this operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a + previous operation, this field points to the UUID of the operation + being retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/transactions/{txnid}/status: + get: + description: Gets the status of a transaction + operationId: getTxnStatusNamespace + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + details: + description: A set of records describing the activities within + the transaction known by the local FireFly node + items: + description: A set of records describing the activities within + the transaction known by the local FireFly node + properties: + error: + description: If an error occurred related to the detail + entry, it is included here + type: string + id: + description: The UUID of the entry referenced by this detail. + The type of this record can be inferred from the entry + type + format: uuid + type: string + info: + additionalProperties: + description: Output details for this entry + description: Output details for this entry + type: object + status: + description: The status of the detail record. Cases where + an event is required for completion, but has not arrived + yet are marked with a 'pending' record + type: string + subtype: + description: A sub-type, such as an operation type, or an + event type + type: string + timestamp: + description: The time relevant to when the record was updated, + such as the time an event was created, or the last update + time of an operation + format: date-time + type: string + type: + description: The type of the transaction status detail record + type: string + type: object + type: array + status: + description: The overall computed status of the transaction, after + analyzing the details during the API call + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/verifiers: + get: + description: Gets a list of verifiers + operationId: getVerifiersNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: identity + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: value + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time this verifier was created on this node + format: date-time + type: string + hash: + description: Hash used as a globally consistent identifier for + this namespace + type + value combination on every node in + the network + format: byte + type: string + identity: + description: The UUID of the parent identity that has claimed + this verifier + format: uuid + type: string + namespace: + description: The namespace of the verifier + type: string + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/verifiers/{hash}: + get: + description: Gets a verifier by its hash + operationId: getVerifierByIDNamespace + parameters: + - description: The hash of the verifier + in: path + name: hash + required: true + schema: + example: hash + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time this verifier was created on this node + format: date-time + type: string + hash: + description: Hash used as a globally consistent identifier for + this namespace + type + value combination on every node in the + network + format: byte + type: string + identity: + description: The UUID of the parent identity that has claimed + this verifier + format: uuid + type: string + namespace: + description: The namespace of the verifier + type: string + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/verifiers/resolve: + post: + description: Resolves an input key to a signing key + operationId: postVerifiersResolveNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, or + Fabric MSP identifier + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /network/action: + post: + description: Notify all nodes in the network of a new governance action + operationId: postNetworkAction + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + type: + description: The action to be performed + enum: + - terminate + type: string + type: object + responses: + "202": + content: + application/json: + schema: + properties: + type: + description: The action to be performed + enum: + - terminate + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/diddocs/{did}: + get: + description: Gets a DID document by its DID + operationId: getNetworkDIDDocByDID + parameters: + - description: The identity DID + in: path + name: did + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + '@context': + description: See https://www.w3.org/TR/did-core/#json-ld + items: + description: See https://www.w3.org/TR/did-core/#json-ld + type: string + type: array + authentication: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + type: array + id: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + verificationMethod: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + properties: + blockchainAcountId: + description: For blockchains like Ethereum that represent + signing identities directly by their public key summarized + in an account string + type: string + controller: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + dataExchangePeerID: + description: A string provided by your Data Exchange plugin, + that it uses a technology specific mechanism to validate + against when messages arrive from this identity + type: string + id: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + mspIdentityString: + description: For Hyperledger Fabric where the signing identity + is represented by an MSP identifier (containing X509 certificate + DN strings) that were validated by your local MSP + type: string + type: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/identities: + get: + deprecated: true + description: Gets the list of identities in the network (deprecated - use /identities + instead of /network/identities + operationId: getNetworkIdentities + parameters: + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to + prove data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum + address, or Fabric MSP identifier + type: string + type: object + type: array + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /network/identities/{did}: + get: + deprecated: true + description: Gets an identity by its DID + operationId: getNetworkIdentityByDID + parameters: + - description: The identity DID + in: path + name: did + required: true + schema: + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, that + have been bound to this identity and can be used to prove data + orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/nodes: + get: + description: Gets a list of nodes in the network + operationId: getNetworkNodes + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /network/nodes/{nameOrId}: + get: + description: Gets information about a specific node in the network + operationId: getNetworkNode + parameters: + - description: The name or ID of the node + in: path + name: nameOrId + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/nodes/self: + post: + description: Instructs this FireFly node to register itself on the network + operationId: postNodesSelf + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + additionalProperties: {} + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/organizations: + get: + description: Gets a list of orgs in the network + operationId: getNetworkOrgs + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Registers a new org in the network + operationId: postNewOrganization + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + key: + description: The blockchain signing key to use to make the claim + to the identity. Must be available to the local node to sign the + identity claim. Will become a verifier on the established identity + type: string + name: + description: The name of the identity. The name must be unique within + the type and namespace + type: string + parent: + description: On input the parent can be specified directly as the + UUID of and existing identity, or as a DID to resolve to that + identity, or an organization name. The parent must already have + been registered, and its blockchain signing key must be available + to the local node to sign the verification + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/organizations/{nameOrId}: + get: + description: Gets information about a specific org in the network + operationId: getNetworkOrg + parameters: + - description: The name or ID of the org + in: path + name: nameOrId + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/organizations/self: + post: + description: Instructs this FireFly node to register its org on the network + operationId: postNewOrganizationSelf + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + additionalProperties: {} + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /nextpins: + get: + description: Queries the list of next-pins that determine the next masked message + sequence for each member of a privacy group, on each context/topic + operationId: getNextPins + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: context + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: identity + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: nonce + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + context: + description: 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 + format: byte + type: string + hash: + description: The unique masked pin string + format: byte + type: string + identity: + description: The member of the privacy group the next-pin applies + to + type: string + namespace: + description: The namespace of the next-pin + type: string + nonce: + description: The numeric index - which is monotonically increasing + for each member of the privacy group + format: int64 + type: integer + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /operations: + get: + description: Gets a a list of operations + operationId: getOps + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: error + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: input + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: output + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: plugin + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: retry + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: status + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for + this operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a + previous operation, this field points to the UUID of the operation + being retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /operations/{opid}: + get: + description: Gets an operation by ID + operationId: getOpByID + parameters: + - description: The operation ID key to get + in: path + name: opid + required: true + schema: + type: string + - description: When set, the API will return additional status information if + available + in: query + name: fetchstatus + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + detail: + description: Additional detailed information about an operation + provided by the connector + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /operations/{opid}/retry: + post: + description: Retries a failed operation + operationId: postOpRetry + parameters: + - description: The UUID of the operation + in: path + name: opid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + additionalProperties: {} + type: object + responses: + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /pins: + get: + description: Queries the list of pins received from the blockchain + operationId: getPins + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: dispatched + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: index + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: masked + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + batch: + description: The UUID of the batch of messages this pin is part + of + format: uuid + type: string + batchHash: + description: The manifest hash batch of messages this pin is + part of + format: byte + type: string + created: + description: The time the FireFly node created the pin + format: date-time + type: string + dispatched: + description: Once true, this pin has been processed and will + not be processed again + type: boolean + hash: + description: The hash represents a topic within a message in + the batch. If a message has multiple topics, then multiple + pins are created. If the message is private, the hash is masked + for privacy + format: byte + type: string + index: + description: The index of this pin within the batch. One pin + is created for each topic, of each message in the batch + format: int64 + type: integer + masked: + description: True if the pin is for a private message, and hence + is masked with the group ID and salted with a nonce so observers + of the blockchain cannot use pin hash to match this transaction + to other transactions or participants + type: boolean + namespace: + description: The namespace of the pin + type: string + sequence: + description: The order of the pin in the local FireFly database, + which matches the order in which pins were delivered to FireFly + by the blockchain connector event stream + format: int64 + type: integer + signer: + description: The blockchain signing key that submitted this + transaction, as passed through to FireFly by the smart contract + that emitted the blockchain event + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /pins/rewind: + post: + description: Force a rewind of the event aggregator to a previous position, + to re-evaluate (and possibly dispatch) that pin and others after it. Only + accepts a sequence or batch ID for a currently undispatched pin + operationId: postPinsRewind + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + batch: + description: The ID of the batch to which the event aggregator should + rewind. Either sequence or batch must be specified + format: uuid + type: string + sequence: + description: The sequence of the pin to which the event aggregator + should rewind. Either sequence or batch must be specified + format: int64 + type: integer + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The ID of the batch to which the event aggregator + should rewind. Either sequence or batch must be specified + format: uuid + type: string + sequence: + description: The sequence of the pin to which the event aggregator + should rewind. Either sequence or batch must be specified + format: int64 + type: integer + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /status: + get: + description: Gets the status of this namespace + operationId: getStatus + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + multiparty: + description: Information about the multi-party system configured + on this namespace + properties: + contract: + description: Information about the multi-party smart contract + configured for this namespace + properties: + active: + description: The currently active FireFly smart contract + properties: + firstEvent: + description: 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 + type: string + index: + description: The index of this contract in the config + file + type: integer + info: + description: Additional info about the current status + of the multi-party contract + properties: + finalEvent: + description: The identifier for the final blockchain + event received from this contract before termination + type: string + subscription: + description: The backend identifier of the subscription + for the FireFly BatchPin contract + type: string + version: + description: The version of this multiparty contract + type: integer + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + type: object + terminated: + description: Previously-terminated FireFly smart contracts + items: + description: Previously-terminated FireFly smart contracts + properties: + firstEvent: + description: 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 + type: string + index: + description: The index of this contract in the config + file + type: integer + info: + description: Additional info about the current status + of the multi-party contract + properties: + finalEvent: + description: The identifier for the final blockchain + event received from this contract before termination + type: string + subscription: + description: The backend identifier of the subscription + for the FireFly BatchPin contract + type: string + version: + description: The version of this multiparty + contract + type: integer + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a + Fabric chaincode name and channel + type: object + type: array + type: object + enabled: + description: Whether multi-party mode is enabled for this + namespace + type: boolean + type: object + namespace: + description: The namespace that this status applies to + properties: + created: + description: The time the namespace was created + format: date-time + type: string + description: + description: A description of the namespace + type: string + name: + description: The local namespace name + type: string + networkName: + description: The shared namespace name within the multiparty + network + type: string + type: object + node: + description: Details of the local node + properties: + id: + description: The UUID of the node, if registered + format: uuid + type: string + name: + description: The name of this node, as specified in the local + configuration + type: string + registered: + description: Whether the node has been successfully registered + type: boolean + type: object + org: + description: Details of the root organization identity registered + for this namespace on the local node + properties: + did: + description: The DID of the organization identity, if registered + type: string + id: + description: The UUID of the organization, if registered + format: uuid + type: string + name: + description: The name of the node operator organization, as + specified in the local configuration + type: string + registered: + description: Whether the organization has been successfully + registered + type: boolean + verifiers: + description: Array of verifiers (blockchain keys) owned by + this identity + items: + description: Array of verifiers (blockchain keys) owned + by this identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum + address, or Fabric MSP identifier + type: string + type: object + type: array + type: object + plugins: + description: Information about plugins configured on this namespace + properties: + blockchain: + description: The blockchain plugins on this namespace + items: + description: The blockchain plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + dataExchange: + description: The data exchange plugins on this namespace + items: + description: The data exchange plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + database: + description: The database plugins on this namespace + items: + description: The database plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + events: + description: The event plugins on this namespace + items: + description: The event plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + identity: + description: The identity plugins on this namespace + items: + description: The identity plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + sharedStorage: + description: The shared storage plugins on this namespace + items: + description: The shared storage plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + tokens: + description: The token plugins on this namespace + items: + description: The token plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + type: object + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /status/batchmanager: + get: + description: Gets the status of the batch manager + operationId: getStatusBatchManager + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + processors: + description: An array of currently active batch processors + items: + description: An array of currently active batch processors + properties: + dispatcher: + description: The type of dispatcher for this processor + type: string + name: + description: The name of the processor, which includes details + of the attributes of message are allocated to this processor + type: string + status: + description: The flush status for this batch processor + properties: + averageBatchBytes: + description: The average byte size of each batch + format: int64 + type: integer + averageBatchData: + description: The average number of data attachments + included in each batch + format: double + type: number + averageBatchMessages: + description: The average number of messages included + in each batch + format: double + type: number + averageFlushTimeMS: + description: The average amount of time spent flushing + each batch + format: int64 + type: integer + blocked: + description: True if the batch flush is in a retry loop, + due to errors being returned by the plugins + type: boolean + cancelled: + description: True if the current batch flush has been + cancelled + type: boolean + flushing: + description: If a flush is in progress, this is the + UUID of the batch being flushed + format: uuid + type: string + lastFlushError: + description: The last error received by this batch processor + while flushing + type: string + lastFlushErrorTime: + description: The time of the last flush + format: date-time + type: string + lastFlushStartTime: + description: The last time a flush was performed + format: date-time + type: string + totalBatches: + description: The total count of batches flushed by this + processor since it started + format: int64 + type: integer + totalErrors: + description: The total count of error flushed encountered + by this processor since it started + format: int64 + type: integer + type: object + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /status/multiparty: + get: + description: Gets the registration status of this organization and node on the + configured multiparty network + operationId: getStatusMultiparty + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + contracts: + description: Information about the active and terminated multi-party + smart contracts configured for this namespace + properties: + active: + description: The currently active FireFly smart contract + properties: + firstEvent: + description: 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 + type: string + index: + description: The index of this contract in the config + file + type: integer + info: + description: Additional info about the current status + of the multi-party contract + properties: + finalEvent: + description: The identifier for the final blockchain + event received from this contract before termination + type: string + subscription: + description: The backend identifier of the subscription + for the FireFly BatchPin contract + type: string + version: + description: The version of this multiparty contract + type: integer + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + status: + description: The status of the contract listener. One + of 'syncing', 'synced', or 'unknown' + type: string + type: object + terminated: + description: Previously-terminated FireFly smart contracts + items: + description: Previously-terminated FireFly smart contracts + properties: + firstEvent: + description: 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 + type: string + index: + description: The index of this contract in the config + file + type: integer + info: + description: Additional info about the current status + of the multi-party contract + properties: + finalEvent: + description: The identifier for the final blockchain + event received from this contract before termination + type: string + subscription: + description: The backend identifier of the subscription + for the FireFly BatchPin contract + type: string + version: + description: The version of this multiparty contract + type: integer + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + type: object + type: array + type: object + enabled: + description: Whether multi-party mode is enabled for this namespace + type: boolean + node: + description: Details of the local node + properties: + pendingRegistrationMessageId: + description: The ID of the pending message that broadcast + the identity claim to the network + format: uuid + type: string + status: + description: The status of the node registration, one of 'unregistered', + 'registering', 'registered', and 'unknown' + type: string + type: object + org: + description: Details of the root organization identity registered + for this namespace on the local node + properties: + pendingRegistrationMessageId: + description: The ID of the pending message that broadcast + the identity claim to the network + format: uuid + type: string + status: + description: The status of the organization registration, + one of 'unregistered', 'registering', 'registered', and + 'unknown' + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /subscriptions: + get: + description: Gets a list of subscriptions + operationId: getSubscriptions + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: events + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: filters + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: options + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: transport + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' + instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event + in the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this + filter is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the + subscription + type: string + options: + description: Subscription options + properties: + batch: + description: 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. + type: boolean + batchTimeout: + description: When batching is enabled, the optional timeout + to send events even when the batch hasn't filled. + type: string + fastack: + description: 'Webhooks only: When true the event will be + acknowledged before the webhook is invoked, allowing parallel + invocations' + type: boolean + firstEvent: + description: 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on + the webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + httpOptions: + description: 'Webhooks only: a set of options for HTTP' + properties: + connectionTimeout: + description: The maximum amount of time that a connection + is allowed to remain with no data transmitted. + type: string + expectContinueTimeout: + description: See [ExpectContinueTimeout in the Go docs](https://pkg.go.dev/net/http#Transport) + type: string + idleTimeout: + description: The max duration to hold a HTTP keepalive + connection between calls + type: string + maxIdleConns: + description: The max number of idle connections to hold + pooled + type: integer + proxyURL: + description: HTTP proxy URL to use for outbound requests + to the webhook + type: string + requestTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + tlsHandshakeTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + type: object + input: + description: 'Webhooks only: A set of options to extract + data from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data + input, to use for the request body. Default is the + whole first body + type: string + headers: + description: A top-level property of the first data + input, to use for headers + type: string + path: + description: A top-level property of the first data + input, to use for a path to append with escaping to + the webhook path + type: string + query: + description: A top-level property of the first data + input, to use for query parameters + type: string + replytx: + description: A top-level property of the first data + input, to use to dynamically set whether to pin the + response (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set + on the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply + message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set + on the reply message' + type: string + retry: + description: 'Webhooks only: a set of options for retrying + the webhook call' + properties: + count: + description: Number of times to retry the webhook call + in case of failure + type: integer + enabled: + description: Enables retry on HTTP calls, defaults to + false + type: boolean + initialDelay: + description: Initial delay between retries when we retry + the webhook call + type: string + maxDelay: + description: Max delay between retries when we retry + the webhookcall + type: string + type: object + tlsConfigName: + description: The name of an existing TLS configuration associated + to the namespace to use + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be + relative if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates a new subscription for an application to receive events + from FireFly + operationId: postNewSubscription + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an event + is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription will + only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + batch: + description: 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. + type: boolean + batchTimeout: + description: When batching is enabled, the optional timeout + to send events even when the batch hasn't filled. + type: string + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the webhook + request' + type: object + httpOptions: + description: 'Webhooks only: a set of options for HTTP' + properties: + connectionTimeout: + description: The maximum amount of time that a connection + is allowed to remain with no data transmitted. + type: string + expectContinueTimeout: + description: See [ExpectContinueTimeout in the Go docs](https://pkg.go.dev/net/http#Transport) + type: string + idleTimeout: + description: The max duration to hold a HTTP keepalive connection + between calls + type: string + maxIdleConns: + description: The max number of idle connections to hold + pooled + type: integer + proxyURL: + description: HTTP proxy URL to use for outbound requests + to the webhook + type: string + requestTimeout: + description: The max duration to hold a TLS handshake alive + type: string + tlsHandshakeTimeout: + description: The max duration to hold a TLS handshake alive + type: string + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. Only + applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set on + the webhook request' + type: string + description: 'Webhooks only: Static query params to set on the + webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send a + reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + retry: + description: 'Webhooks only: a set of options for retrying the + webhook call' + properties: + count: + description: Number of times to retry the webhook call in + case of failure + type: integer + enabled: + description: Enables retry on HTTP calls, defaults to false + type: boolean + initialDelay: + description: Initial delay between retries when we retry + the webhook call + type: string + maxDelay: + description: Max delay between retries when we retry the + webhookcall + type: string + type: object + tlsConfigName: + description: The name of an existing TLS configuration associated + to the namespace to use + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + type: object + responses: + "201": + content: + application/json: + schema: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + batch: + description: 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. + type: boolean + batchTimeout: + description: When batching is enabled, the optional timeout + to send events even when the batch hasn't filled. + type: string + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + httpOptions: + description: 'Webhooks only: a set of options for HTTP' + properties: + connectionTimeout: + description: The maximum amount of time that a connection + is allowed to remain with no data transmitted. + type: string + expectContinueTimeout: + description: See [ExpectContinueTimeout in the Go docs](https://pkg.go.dev/net/http#Transport) + type: string + idleTimeout: + description: The max duration to hold a HTTP keepalive + connection between calls + type: string + maxIdleConns: + description: The max number of idle connections to hold + pooled + type: integer + proxyURL: + description: HTTP proxy URL to use for outbound requests + to the webhook + type: string + requestTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + tlsHandshakeTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set on + the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + retry: + description: 'Webhooks only: a set of options for retrying + the webhook call' + properties: + count: + description: Number of times to retry the webhook call + in case of failure + type: integer + enabled: + description: Enables retry on HTTP calls, defaults to + false + type: boolean + initialDelay: + description: Initial delay between retries when we retry + the webhook call + type: string + maxDelay: + description: Max delay between retries when we retry the + webhookcall + type: string + type: object + tlsConfigName: + description: The name of an existing TLS configuration associated + to the namespace to use + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + put: + description: Update an existing subscription + operationId: putSubscription + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an event + is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription will + only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + batch: + description: 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. + type: boolean + batchTimeout: + description: When batching is enabled, the optional timeout + to send events even when the batch hasn't filled. + type: string + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the webhook + request' + type: object + httpOptions: + description: 'Webhooks only: a set of options for HTTP' + properties: + connectionTimeout: + description: The maximum amount of time that a connection + is allowed to remain with no data transmitted. + type: string + expectContinueTimeout: + description: See [ExpectContinueTimeout in the Go docs](https://pkg.go.dev/net/http#Transport) + type: string + idleTimeout: + description: The max duration to hold a HTTP keepalive connection + between calls + type: string + maxIdleConns: + description: The max number of idle connections to hold + pooled + type: integer + proxyURL: + description: HTTP proxy URL to use for outbound requests + to the webhook + type: string + requestTimeout: + description: The max duration to hold a TLS handshake alive + type: string + tlsHandshakeTimeout: + description: The max duration to hold a TLS handshake alive + type: string + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. Only + applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set on + the webhook request' + type: string + description: 'Webhooks only: Static query params to set on the + webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send a + reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + retry: + description: 'Webhooks only: a set of options for retrying the + webhook call' + properties: + count: + description: Number of times to retry the webhook call in + case of failure + type: integer + enabled: + description: Enables retry on HTTP calls, defaults to false + type: boolean + initialDelay: + description: Initial delay between retries when we retry + the webhook call + type: string + maxDelay: + description: Max delay between retries when we retry the + webhookcall + type: string + type: object + tlsConfigName: + description: The name of an existing TLS configuration associated + to the namespace to use + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + batch: + description: 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. + type: boolean + batchTimeout: + description: When batching is enabled, the optional timeout + to send events even when the batch hasn't filled. + type: string + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + httpOptions: + description: 'Webhooks only: a set of options for HTTP' + properties: + connectionTimeout: + description: The maximum amount of time that a connection + is allowed to remain with no data transmitted. + type: string + expectContinueTimeout: + description: See [ExpectContinueTimeout in the Go docs](https://pkg.go.dev/net/http#Transport) + type: string + idleTimeout: + description: The max duration to hold a HTTP keepalive + connection between calls + type: string + maxIdleConns: + description: The max number of idle connections to hold + pooled + type: integer + proxyURL: + description: HTTP proxy URL to use for outbound requests + to the webhook + type: string + requestTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + tlsHandshakeTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set on + the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + retry: + description: 'Webhooks only: a set of options for retrying + the webhook call' + properties: + count: + description: Number of times to retry the webhook call + in case of failure + type: integer + enabled: + description: Enables retry on HTTP calls, defaults to + false + type: boolean + initialDelay: + description: Initial delay between retries when we retry + the webhook call + type: string + maxDelay: + description: Max delay between retries when we retry the + webhookcall + type: string + type: object + tlsConfigName: + description: The name of an existing TLS configuration associated + to the namespace to use + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /subscriptions/{subid}: + delete: + description: Deletes a subscription + operationId: deleteSubscription + parameters: + - description: The subscription ID + in: path + name: subid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Default Namespace + get: + description: Gets a subscription by its ID + operationId: getSubscriptionByID + parameters: + - description: The subscription ID + in: path + name: subid + required: true + schema: + type: string + - description: When set, the API will return additional status information if + available + in: query + name: fetchstatus + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + batch: + description: 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. + type: boolean + batchTimeout: + description: When batching is enabled, the optional timeout + to send events even when the batch hasn't filled. + type: string + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + httpOptions: + description: 'Webhooks only: a set of options for HTTP' + properties: + connectionTimeout: + description: The maximum amount of time that a connection + is allowed to remain with no data transmitted. + type: string + expectContinueTimeout: + description: See [ExpectContinueTimeout in the Go docs](https://pkg.go.dev/net/http#Transport) + type: string + idleTimeout: + description: The max duration to hold a HTTP keepalive + connection between calls + type: string + maxIdleConns: + description: The max number of idle connections to hold + pooled + type: integer + proxyURL: + description: HTTP proxy URL to use for outbound requests + to the webhook + type: string + requestTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + tlsHandshakeTimeout: + description: The max duration to hold a TLS handshake + alive + type: string + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set on + the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + retry: + description: 'Webhooks only: a set of options for retrying + the webhook call' + properties: + count: + description: Number of times to retry the webhook call + in case of failure + type: integer + enabled: + description: Enables retry on HTTP calls, defaults to + false + type: boolean + initialDelay: + description: Initial delay between retries when we retry + the webhook call + type: string + maxDelay: + description: Max delay between retries when we retry the + webhookcall + type: string + type: object + tlsConfigName: + description: The name of an existing TLS configuration associated + to the namespace to use + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /subscriptions/{subid}/events: + get: + description: Gets a collection of events filtered by the subscription for further + filtering + operationId: getSubscriptionEventsFiltered + parameters: + - description: The subscription ID + in: path + name: subid + required: true + schema: + type: string + - description: The sequence ID in the raw event stream to start indexing through + events from. Leave blank to start indexing from the most recent events + in: query + name: startsequence + schema: + type: string + - description: The sequence ID in the raw event stream to stop indexing through + events at. Leave blank to start indexing from the most recent events + in: query + name: endsequence + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: correlator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: reference + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part + of. Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/accounts: + get: + description: Gets a list of token accounts + operationId: getTokenAccounts + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + key: + description: The blockchain signing identity this balance applies + to + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/accounts/{key}/pools: + get: + description: Gets a list of token pools that contain a given token account key + operationId: getTokenAccountPools + parameters: + - description: The key for the token account. The exact format may vary based + on the token connector use + in: path + name: key + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + pool: + description: The UUID the token pool this balance entry applies + to + format: uuid + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/approvals: + get: + description: Gets a list of token approvals + operationId: getTokenApprovals + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: active + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: approved + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainevent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: localid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messagehash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: operator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: protocolid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: subject + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + active: + description: Indicates if this approval is currently active + (only one approval can be active per subject) + type: boolean + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes + permission (false) + type: boolean + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the token approval + format: date-time + type: string + info: + additionalProperties: + description: 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 + description: 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 + type: object + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token approval, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated + with this approval using the data field of the approval in + a compatible token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated + with this approval using the data field of the approval in + a compatible token connector + format: byte + type: string + namespace: + description: The namespace for the approval, which must match + the namespace of the token pool + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + subject: + description: A string identifying the parties and entities in + the scope of this approval, as provided by the token connector + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in + use supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates a token approval + operationId: postTokenApproval + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes permission + (false) + type: boolean + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the approval. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the approval. See your chosen token connector documentation + for details + type: object + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + message: + description: You can specify a message to correlate with the approval, + which can be of type broadcast or private. Your chosen token connector + and on-chain smart contract must support on-chain/off-chain correlation + by taking a `data` input on the approval + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + active: + description: Indicates if this approval is currently active (only + one approval can be active per subject) + type: boolean + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes permission + (false) + type: boolean + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the token approval + format: date-time + type: string + info: + additionalProperties: + description: 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 + description: 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 + type: object + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token approval, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the approval, which must match + the namespace of the token pool + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + subject: + description: A string identifying the parties and entities in + the scope of this approval, as provided by the token connector + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + active: + description: Indicates if this approval is currently active (only + one approval can be active per subject) + type: boolean + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes permission + (false) + type: boolean + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the token approval + format: date-time + type: string + info: + additionalProperties: + description: 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 + description: 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 + type: object + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token approval, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the approval, which must match + the namespace of the token pool + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + subject: + description: A string identifying the parties and entities in + the scope of this approval, as provided by the token connector + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/balances: + get: + description: Gets a list of token balances + operationId: getTokenBalances + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: balance + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tokenindex + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: uri + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + balance: + description: The numeric balance. For non-fungible tokens will + always be 1. For fungible tokens, the number of decimals for + the token pool should be considered when interpreting the + balance. For example, with 18 decimals a fractional balance + of 10.234 will be returned as 10,234,000,000,000,000,000 + type: string + connector: + description: The token connector that is responsible for the + token pool of this balance entry + type: string + key: + description: The blockchain signing identity this balance applies + to + type: string + namespace: + description: The namespace of the token pool for this balance + entry + type: string + pool: + description: The UUID the token pool this balance entry applies + to + format: uuid + type: string + tokenIndex: + description: The index of the token within the pool that this + balance applies to + type: string + updated: + description: The last time the balance was updated by applying + a transfer event + format: date-time + type: string + uri: + description: The URI of the token this balance entry applies + to + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/burn: + post: + description: Burns some tokens + operationId: postTokenBurn + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + type: object + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + message: + description: You can specify a message to correlate with the transfer, + which can be of type broadcast or private. Your chosen token connector + and on-chain smart contract must support on-chain/off-chain correlation + by taking a `data` input on the transfer + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + pool: + description: The name or UUID of a token pool + type: string + tokenIndex: + description: The index of the token within the pool that this transfer + applies to + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/connectors: + get: + description: Gets the list of token connectors currently in use + operationId: getTokenConnectors + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + name: + description: The name of the token connector, as configured + in the FireFly core configuration file + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/mint: + post: + description: Mints some tokens + operationId: postTokenMint + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + type: object + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + message: + description: You can specify a message to correlate with the transfer, + which can be of type broadcast or private. Your chosen token connector + and on-chain smart contract must support on-chain/off-chain correlation + by taking a `data` input on the transfer + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + pool: + description: The name or UUID of a token pool + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this transfer + applies to + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/pools: + get: + description: Gets a list of token pools + operationId: getTokenPools + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: active + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: decimals + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interfaceformat + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: locator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: networkname + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: published + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: standard + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: symbol + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + active: + description: Indicates whether the pool has been successfully + activated with the token connector + type: boolean + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for + details + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + interfaceFormat: + description: The interface encoding format supported by the + connector for this token pool + enum: + - abi + - ffi + type: string + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network about this pool + format: uuid + type: string + methods: + description: The method definitions resolved by the token connector + to be used by each token operation + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + networkName: + description: The published name of the token pool within the + multiparty network + type: string + published: + description: Indicates if the token pool is published to other + members of the multiparty network + type: boolean + standard: + description: The ERC standard the token pool conforms to, as + reported by the token connector + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates a new token pool + operationId: postTokenPool + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: When true the definition will be published to all other members + of the multiparty network + in: query + name: publish + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + config: + additionalProperties: + description: 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 + description: 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 + type: object + connector: + description: 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 + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + key: + description: 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 + type: string + name: + description: The name of the token pool. Note the name is not validated + against the description of the token on the blockchain + type: string + networkName: + description: The published name of the token pool within the multiparty + network + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + active: + description: Indicates whether the pool has been successfully + activated with the token connector + type: boolean + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + interfaceFormat: + description: The interface encoding format supported by the connector + for this token pool + enum: + - abi + - ffi + type: string + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network about this pool + format: uuid + type: string + methods: + description: The method definitions resolved by the token connector + to be used by each token operation + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + networkName: + description: The published name of the token pool within the multiparty + network + type: string + published: + description: Indicates if the token pool is published to other + members of the multiparty network + type: boolean + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + active: + description: Indicates whether the pool has been successfully + activated with the token connector + type: boolean + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + interfaceFormat: + description: The interface encoding format supported by the connector + for this token pool + enum: + - abi + - ffi + type: string + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network about this pool + format: uuid + type: string + methods: + description: The method definitions resolved by the token connector + to be used by each token operation + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + networkName: + description: The published name of the token pool within the multiparty + network + type: string + published: + description: Indicates if the token pool is published to other + members of the multiparty network + type: boolean + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/pools/{nameOrId}: + delete: + description: Delete a token pool + operationId: deleteTokenPool + parameters: + - description: The token pool name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Default Namespace + get: + description: Gets a token pool by its name or its ID + operationId: getTokenPoolByNameOrID + parameters: + - description: The token pool name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + active: + description: Indicates whether the pool has been successfully + activated with the token connector + type: boolean + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + interfaceFormat: + description: The interface encoding format supported by the connector + for this token pool + enum: + - abi + - ffi + type: string + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network about this pool + format: uuid + type: string + methods: + description: The method definitions resolved by the token connector + to be used by each token operation + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + networkName: + description: The published name of the token pool within the multiparty + network + type: string + published: + description: Indicates if the token pool is published to other + members of the multiparty network + type: boolean + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/pools/{nameOrId}/publish: + post: + description: Publish a token pool to all other members of the multiparty network + operationId: postTokenPoolPublish + parameters: + - description: The token pool name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + networkName: + description: An optional name to be used for publishing this definition + to the multiparty network, which may differ from the local name + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + active: + description: Indicates whether the pool has been successfully + activated with the token connector + type: boolean + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + interfaceFormat: + description: The interface encoding format supported by the connector + for this token pool + enum: + - abi + - ffi + type: string + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network about this pool + format: uuid + type: string + methods: + description: The method definitions resolved by the token connector + to be used by each token operation + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + networkName: + description: The published name of the token pool within the multiparty + network + type: string + published: + description: Indicates if the token pool is published to other + members of the multiparty network + type: boolean + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + active: + description: Indicates whether the pool has been successfully + activated with the token connector + type: boolean + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the token contract + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + interfaceFormat: + description: The interface encoding format supported by the connector + for this token pool + enum: + - abi + - ffi + type: string + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network about this pool + format: uuid + type: string + methods: + description: The method definitions resolved by the token connector + to be used by each token operation + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + networkName: + description: The published name of the token pool within the multiparty + network + type: string + published: + description: Indicates if the token pool is published to other + members of the multiparty network + type: boolean + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/transfers: + get: + description: Gets a list of token transfers + operationId: getTokenTransfers + parameters: + - description: The sending or receiving token account for a token transfer + in: query + name: fromOrTo + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: amount + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainevent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: from + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: localid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messagehash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: protocolid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: to + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tokenindex + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: uri + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On + input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated + with this transfer using the data field of the transfer in + a compatible token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated + with this transfer using the data field of the transfer in + a compatible token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in + use supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Transfers some tokens + operationId: postTokenTransfer + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + type: object + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + message: + description: You can specify a message to correlate with the transfer, + which can be of type broadcast or private. Your chosen token connector + and on-chain smart contract must support on-chain/off-chain correlation + by taking a `data` input on the transfer + properties: + data: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + items: + description: For input allows you to specify data in-line + in the message, that will be turned into data attachments. + For output when fetchdata is used on API calls, includes + the in-line data payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic + versioning is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using + the header.group to specify the hash of a group that has been + previously resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input + can be a UUID or org name, and will be resolved + to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will + be picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to + have multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + pool: + description: The name or UUID of a token pool + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this transfer + applies to + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/transfers/{transferId}: + get: + description: Gets a token transfer by its ID + operationId: getTokenTransferByID + parameters: + - description: The token transfer ID + in: path + name: transferId + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /transactions: + get: + description: Gets a list of transactions + operationId: getTxns + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainids + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + blockchainIds: + description: 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 + items: + description: 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 + type: string + type: array + created: + description: 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 + format: date-time + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + idempotencyKey: + description: An optional unique identifier for a transaction. + Cannot be duplicated within a namespace, thus allowing idempotent + submission of transactions to the API + type: string + namespace: + description: The namespace of the FireFly transaction + type: string + type: + description: The type of the FireFly transaction + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /transactions/{txnid}: + get: + description: Gets a transaction by its ID + operationId: getTxnByID + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainids + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + properties: + blockchainIds: + description: 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 + items: + description: 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 + type: string + type: array + created: + description: 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 + format: date-time + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + idempotencyKey: + description: An optional unique identifier for a transaction. + Cannot be duplicated within a namespace, thus allowing idempotent + submission of transactions to the API + type: string + namespace: + description: The namespace of the FireFly transaction + type: string + type: + description: The type of the FireFly transaction + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - contract_invoke_pin + - token_approval + - data_publish + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /transactions/{txnid}/blockchainevents: + get: + description: Gets a list blockchain events for a specific transaction + operationId: getTxnBlockchainEvents + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + id: + description: The UUID assigned to the event by FireFly + format: uuid + type: string + info: + additionalProperties: + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + type: object + listener: + description: The UUID of the listener that detected this event, + or nil for built-in events in the system namespace + format: uuid + type: string + name: + description: The name of the event in the blockchain smart contract + type: string + namespace: + description: The namespace of the listener that detected this + blockchain event + type: string + output: + additionalProperties: + description: The data output by the event, parsed to JSON + according to the interface of the smart contract + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + type: object + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely on the blockchain (convention for plugins + is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) + type: string + source: + description: The blockchain plugin or token service that detected + the event + type: string + timestamp: + description: The time allocated to this event by the blockchain. + This is the block timestamp for most blockchain connectors + format: date-time + type: string + tx: + description: 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 + properties: + blockchainId: + description: The blockchain transaction ID, in the format + specific to the blockchain involved in the transaction. + Not all FireFly transactions include a blockchain + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /transactions/{txnid}/operations: + get: + description: Gets a list of operations in a specific transaction + operationId: getTxnOps + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for + this operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a + previous operation, this field points to the UUID of the operation + being retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /transactions/{txnid}/status: + get: + description: Gets the status of a transaction + operationId: getTxnStatus + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + details: + description: A set of records describing the activities within + the transaction known by the local FireFly node + items: + description: A set of records describing the activities within + the transaction known by the local FireFly node + properties: + error: + description: If an error occurred related to the detail + entry, it is included here + type: string + id: + description: The UUID of the entry referenced by this detail. + The type of this record can be inferred from the entry + type + format: uuid + type: string + info: + additionalProperties: + description: Output details for this entry + description: Output details for this entry + type: object + status: + description: The status of the detail record. Cases where + an event is required for completion, but has not arrived + yet are marked with a 'pending' record + type: string + subtype: + description: A sub-type, such as an operation type, or an + event type + type: string + timestamp: + description: The time relevant to when the record was updated, + such as the time an event was created, or the last update + time of an operation + format: date-time + type: string + type: + description: The type of the transaction status detail record + type: string + type: object + type: array + status: + description: The overall computed status of the transaction, after + analyzing the details during the API call + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /verifiers: + get: + description: Gets a list of verifiers + operationId: getVerifiers + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: identity + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: value + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time this verifier was created on this node + format: date-time + type: string + hash: + description: Hash used as a globally consistent identifier for + this namespace + type + value combination on every node in + the network + format: byte + type: string + identity: + description: The UUID of the parent identity that has claimed + this verifier + format: uuid + type: string + namespace: + description: The namespace of the verifier + type: string + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /verifiers/{hash}: + get: + description: Gets a verifier by its hash + operationId: getVerifierByID + parameters: + - description: The hash of the verifier + in: path + name: hash + required: true + schema: + example: hash + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time this verifier was created on this node + format: date-time + type: string + hash: + description: Hash used as a globally consistent identifier for + this namespace + type + value combination on every node in the + network + format: byte + type: string + identity: + description: The UUID of the parent identity that has claimed + this verifier + format: uuid + type: string + namespace: + description: The namespace of the verifier + type: string + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /verifiers/resolve: + post: + description: Resolves an input key to a signing key + operationId: postVerifiersResolve + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, or + Fabric MSP identifier + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - tezos_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /websockets: + get: + description: Gets a list of the current WebSocket connections to this node + operationId: getWebSockets + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + connections: + description: List of currently active websocket client connections + items: + description: List of currently active websocket client connections + properties: + id: + description: The unique ID assigned to this client connection + type: string + remoteAddress: + description: The remote address of the connected client + (if available) + type: string + subscriptions: + description: List of subscriptions currently started by + this client + items: + description: List of subscriptions currently started by + this client + properties: + ephemeral: + description: Indicates whether the subscription is + ephemeral (vs durable) + type: boolean + filter: + description: The subscription filter specification + properties: + author: + description: 'Deprecated: Please use ''message.author'' + instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. + If an event is not a blockchain event, these + filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to + the blockchain event 'name' field, which + is the name of the event in the underlying + blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the + event type, to subscribe to a subset of event + types + type: string + group: + description: 'Deprecated: Please use ''message.group'' + instead' + type: string + message: + description: Filters specific to message events. + If an event is not a message event, these filters + are ignored + properties: + author: + description: Regular expression to apply to + the message 'header.author' field + type: string + group: + description: Regular expression to apply to + the message 'header.group' field + type: string + tag: + description: Regular expression to apply to + the message 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' + instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' + instead' + type: string + transaction: + description: Filters specific to events with a + transaction. If an event is not associated with + a transaction, this filter is ignored + properties: + type: + description: Regular expression to apply to + the transaction 'type' field + type: string + type: object + type: object + name: + description: The subscription name (for durable subscriptions + only) + type: string + namespace: + description: The subscription namespace + type: string + startTime: + description: The time the subscription started (reset + on dynamic namespace reload) + format: date-time + type: string + type: object + type: array + userAgent: + description: The user agent of the connected client (if + available) + type: string + type: object + type: array + enabled: + description: Indicates whether the websockets plugin is enabled + type: boolean + type: object + description: Success + default: + description: "" + tags: + - Global +servers: +- url: http://localhost:5000/api/v1 diff --git a/v1.3.1/swagger/test.yaml b/v1.3.1/swagger/test.yaml new file mode 100644 index 000000000..c218beaeb --- /dev/null +++ b/v1.3.1/swagger/test.yaml @@ -0,0 +1,35497 @@ +components: {} +info: + title: FireFly + version: "1.0" +openapi: 3.0.2 +paths: + /apis: + get: + description: Gets a list of contract APIs that have been published + operationId: getContractAPIs + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used + to publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the + API + type: string + namespace: + description: The namespace of the contract API + type: string + urls: + description: The URLs to use to access the API + properties: + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates and broadcasts a new custom smart contract API + operationId: postNewContractAPI + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + name: + description: The name that is used in the URL to access the API + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + urls: + description: The URLs to use to access the API + properties: + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + urls: + description: The URLs to use to access the API + properties: + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /apis/{apiName}: + get: + description: Gets information about a contract API, including the URLs for the + OpenAPI Spec and Swagger UI for the API + operationId: getContractAPIByName + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + urls: + description: The URLs to use to access the API + properties: + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /apis/{apiName}/interface: + get: + description: Gets a contract interface for a contract API + operationId: getContractAPIInterface + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /apis/{apiName}/invoke/{methodPath}: + post: + description: Invokes a method on a smart contract API. Performs a blockchain + transaction. + operationId: postContractAPIInvoke + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a method on a smart + contract + in: path + name: methodPath + required: true + schema: + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /apis/{apiName}/listeners/{eventPath}: + get: + description: Gets a list of contract listeners + operationId: getContractAPIListeners + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a event on a smart + contract + in: path + name: eventPath + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: backendid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: location + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: signature + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: The definition of the event, either provided in-line + when creating the listener, or extracted from the referenced + FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For + example an Ethereum contract address, or a Fabric chaincode + name and channel + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: The stringified signature of the event, as computed + by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates a new blockchain listener for events emitted by custom + smart contracts + operationId: postContractAPIListeners + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a event on a smart + contract + in: path + name: eventPath + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + name: + description: A descriptive name for the listener + type: string + options: + description: Options that control how the listener subscribes to + events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + topic: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: The definition of the event, either provided in-line + when creating the listener, or extracted from the referenced + FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and + channel + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: The stringified signature of the event, as computed + by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /apis/{apiName}/query/{methodPath}: + post: + description: Queries a method on a smart contract API. Performs a read-only + query. + operationId: postContractAPIQuery + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a method on a smart + contract + in: path + name: methodPath + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + additionalProperties: {} + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /apis/{id}: + put: + description: The ID of the contract API + operationId: putContractAPI + parameters: + - description: The name of the contract API + in: path + name: id + required: true + schema: + example: id + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + name: + description: The name that is used in the URL to access the API + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + urls: + description: The URLs to use to access the API + properties: + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + urls: + description: The URLs to use to access the API + properties: + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /batches: + get: + description: Gets a list of message batches + operationId: getBatches + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: node + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: payloadref + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + author: + description: The DID of identity of the submitter + type: string + confirmed: + description: The time when the batch was confirmed + format: date-time + type: string + created: + description: The time the batch was sealed + format: date-time + type: string + group: + description: The privacy group the batch is sent to, for private + batches + format: byte + type: string + hash: + description: The hash of the manifest of the batch + format: byte + type: string + id: + description: The UUID of the batch + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + manifest: + description: The manifest of the batch + namespace: + description: The namespace of the batch + type: string + node: + description: The UUID of the node that generated the batch + format: uuid + type: string + tx: + description: The FireFly transaction associated with this batch + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of the batch + enum: + - broadcast + - private + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /batches/{batchid}: + get: + description: Gets a message batch + operationId: getBatchByID + parameters: + - description: The batch ID + in: path + name: batchid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + author: + description: The DID of identity of the submitter + type: string + confirmed: + description: The time when the batch was confirmed + format: date-time + type: string + created: + description: The time the batch was sealed + format: date-time + type: string + group: + description: The privacy group the batch is sent to, for private + batches + format: byte + type: string + hash: + description: The hash of the manifest of the batch + format: byte + type: string + id: + description: The UUID of the batch + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + manifest: + description: The manifest of the batch + namespace: + description: The namespace of the batch + type: string + node: + description: The UUID of the node that generated the batch + format: uuid + type: string + tx: + description: The FireFly transaction associated with this batch + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of the batch + enum: + - broadcast + - private + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /blockchainevents: + get: + description: Gets a list of blockchain events + operationId: getBlockchainEvents + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: listener + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: protocolid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: source + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: timestamp + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.blockchainid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + id: + description: The UUID assigned to the event by FireFly + format: uuid + type: string + info: + additionalProperties: + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + type: object + listener: + description: The UUID of the listener that detected this event, + or nil for built-in events in the system namespace + format: uuid + type: string + name: + description: The name of the event in the blockchain smart contract + type: string + namespace: + description: The namespace of the listener that detected this + blockchain event + type: string + output: + additionalProperties: + description: The data output by the event, parsed to JSON + according to the interface of the smart contract + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + type: object + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely on the blockchain (convention for plugins + is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) + type: string + source: + description: The blockchain plugin or token service that detected + the event + type: string + timestamp: + description: The time allocated to this event by the blockchain. + This is the block timestamp for most blockchain connectors + format: date-time + type: string + tx: + description: 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 + properties: + blockchainId: + description: The blockchain transaction ID, in the format + specific to the blockchain involved in the transaction. + Not all FireFly transactions include a blockchain + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /blockchainevents/{id}: + get: + description: Gets a blockchain event + operationId: getBlockchainEventByID + parameters: + - description: The blockchain event ID + in: path + name: id + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID assigned to the event by FireFly + format: uuid + type: string + info: + additionalProperties: + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + description: Detailed blockchain specific information about the + event, as generated by the blockchain connector + type: object + listener: + description: The UUID of the listener that detected this event, + or nil for built-in events in the system namespace + format: uuid + type: string + name: + description: The name of the event in the blockchain smart contract + type: string + namespace: + description: The namespace of the listener that detected this + blockchain event + type: string + output: + additionalProperties: + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + type: object + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely on the blockchain (convention for plugins + is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) + type: string + source: + description: The blockchain plugin or token service that detected + the event + type: string + timestamp: + description: The time allocated to this event by the blockchain. + This is the block timestamp for most blockchain connectors + format: date-time + type: string + tx: + description: 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 + properties: + blockchainId: + description: The blockchain transaction ID, in the format + specific to the blockchain involved in the transaction. + Not all FireFly transactions include a blockchain + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /charts/histogram/{collection}: + get: + description: Gets a JSON object containing statistics data that can be used + to build a graphical representation of recent activity in a given database + collection + operationId: getChartHistogram + parameters: + - description: The collection ID + in: path + name: collection + required: true + schema: + type: string + - description: Start time of the data to be fetched + in: query + name: startTime + schema: + type: string + - description: End time of the data to be fetched + in: query + name: endTime + schema: + type: string + - description: Number of buckets between start time and end time + in: query + name: buckets + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + count: + description: Total count of entries in this time bucket within + the histogram + type: string + isCapped: + description: Indicates whether there are more results in this + bucket that are not being displayed + type: boolean + timestamp: + description: Starting timestamp for the bucket + format: date-time + type: string + types: + description: Array of separate counts for individual types of + record within the bucket + items: + description: Array of separate counts for individual types + of record within the bucket + properties: + count: + description: Count of entries of a given type within a + bucket + type: string + type: + description: Name of the type + type: string + type: object + type: array + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/deploy: + post: + description: Deploy a new smart contract + operationId: postContractDeploy + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + contract: + description: The smart contract to deploy. This should be pre-compiled + if required by the blockchain connector + definition: + description: The definition of the smart contract + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + description: An optional array of inputs passed to the smart contract's + constructor, if applicable + items: + description: An optional array of inputs passed to the smart contract's + constructor, if applicable + type: array + key: + description: The blockchain signing key that will be used to deploy + the contract. Defaults to the first signing key of the organization + that operates the node + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/interfaces: + get: + description: Gets a list of contract interfaces that have been published + operationId: getContractInterfaces + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: version + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used + to publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used + by the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates and broadcasts a new custom smart contract interface + operationId: postNewContractInterface + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart contract + name + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/interfaces/{interfaceId}: + get: + description: Gets a contract interface by its ID + operationId: getContractInterface + parameters: + - description: The ID of the contract interface + in: path + name: interfaceId + required: true + schema: + type: string + - description: When set, the API will return the full FireFly Interface document + including all methods, events, and parameters + in: query + name: fetchchildren + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/interfaces/{name}/{version}: + get: + description: Gets a contract interface by its name and version + operationId: getContractInterfaceByNameAndVersion + parameters: + - description: The name of the contract interface + in: path + name: name + required: true + schema: + type: string + - description: The version of the contract interface + in: path + name: version + required: true + schema: + type: string + - description: When set, the API will return the full FireFly Interface document + including all methods, events, and parameters + in: query + name: fetchchildren + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/interfaces/generate: + post: + description: A convenience method to convert a blockchain specific smart contract + format into a FireFly Interface format. The specific blockchain plugin in + use must support this functionality. + operationId: postGenerateContractInterface + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: The description of the FFI to be generated. Defaults + to the description extracted by the blockchain specific converter + utility + type: string + input: + description: A blockchain connector specific payload. For example + in Ethereum this is a JSON structure containing an 'abi' array, + and optionally a 'devdocs' array. + name: + description: The name of the FFI to generate + type: string + namespace: + description: The namespace into which the FFI will be generated + type: string + version: + description: The version of the FFI to generate + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/invoke: + post: + description: Invokes a method on a smart contract. Performs a blockchain transaction. + operationId: postContractInvoke + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + errors: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + items: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + interface: + description: The UUID of a method within a pre-configured FireFly + interface (FFI) definition for a smart contract. Required if the + 'method' is omitted. Also see Contract APIs as a way to configure + a dedicated API for your FFI, including all methods and an OpenAPI/Swagger + interface + format: uuid + type: string + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + method: + description: An in-line FFI method definition for the method to + invoke. Required when FFI is not specified + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + methodPath: + description: The pathname of the method on the specified FFI + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/listeners: + get: + description: Gets a list of contract listeners + operationId: getContractListeners + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: backendid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: location + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: signature + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: The definition of the event, either provided in-line + when creating the listener, or extracted from the referenced + FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For + example an Ethereum contract address, or a Fabric chaincode + name and channel + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: The stringified signature of the event, as computed + by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates a new blockchain listener for events emitted by custom + smart contracts + operationId: postNewContractListener + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + event: + description: The definition of the event, either provided in-line + when creating the listener, or extracted from the referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + eventPath: + description: When creating a listener from an existing FFI, this + is the pathname of the event on that FFI to be detected by this + listener + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + name: + description: A descriptive name for the listener + type: string + options: + description: Options that control how the listener subscribes to + events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + topic: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: The definition of the event, either provided in-line + when creating the listener, or extracted from the referenced + FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and + channel + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: The stringified signature of the event, as computed + by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/listeners/{nameOrId}: + delete: + description: Deletes a contract listener referenced by its name or its ID + operationId: deleteContractListener + parameters: + - description: The contract listener name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Default Namespace + get: + description: Gets a contract listener by its name or ID + operationId: getContractListenerByNameOrID + parameters: + - description: The contract listener name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: When set, the API will return additional status information if + available + in: query + name: fetchstatus + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: The definition of the event, either provided in-line + when creating the listener, or extracted from the referenced + FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and + channel + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: The stringified signature of the event, as computed + by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /contracts/query: + post: + description: Queries a method on a smart contract. Performs a read-only query. + operationId: postContractQuery + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + errors: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + items: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + interface: + description: The UUID of a method within a pre-configured FireFly + interface (FFI) definition for a smart contract. Required if the + 'method' is omitted. Also see Contract APIs as a way to configure + a dedicated API for your FFI, including all methods and an OpenAPI/Swagger + interface + format: uuid + type: string + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + method: + description: An in-line FFI method definition for the method to + invoke. Required when FFI is not specified + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + methodPath: + description: The pathname of the method on the specified FFI + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + additionalProperties: {} + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /data: + get: + description: Gets a list of data items + operationId: getData + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.public + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.size + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datatype.name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datatype.version + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: public + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: validator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: value + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the + value and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates a new data item in this FireFly node + operationId: postData + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + datatype: + description: The optional datatype to use for validation of the + in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON type + - object, array, string, number or boolean + type: object + multipart/form-data: + schema: + properties: + autometa: + description: Success + type: string + datatype.name: + description: Success + type: string + datatype.version: + description: Success + type: string + filename.ext: + format: binary + type: string + metadata: + description: Success + type: string + validator: + description: Success + type: string + type: object + responses: + "201": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /data/{dataid}: + get: + description: Gets a data item by its ID, including metadata about this item + operationId: getDataByID + parameters: + - description: The data item ID + in: path + name: dataid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /data/{dataid}/blob: + get: + description: Downloads the original file that was previously uploaded or received + operationId: getDataBlob + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + format: byte + type: string + description: Success + default: + description: "" + tags: + - Default Namespace + /data/{dataid}/blob/publish: + post: + description: Publishes the binary blob attachment stored in your local data + exchange, to shared storage + operationId: postDataBlobPublish + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /data/{dataid}/messages: + get: + description: Gets a list of the messages associated with a data item + operationId: getDataMsgs + parameters: + - description: The data item ID + in: path + name: dataid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /data/{dataid}/value: + get: + description: Downloads the JSON value of the data resource, without the associated + metadata + operationId: getDataValue + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + format: byte + type: string + description: Success + default: + description: "" + tags: + - Default Namespace + /data/{dataid}/value/publish: + post: + description: Publishes the JSON value from the specified data resource, to shared + storage + operationId: postDataValuePublish + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /datatypes: + get: + description: Gets a list of datatypes that have been published + operationId: getDatatypes + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: validator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: version + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used + to publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions + can exist with the same name. Use of semantic versioning is + encourages, such as v1.0.1 + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates and broadcasts a new datatype + operationId: postNewDatatype + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + name: + description: The name of the datatype + type: string + validator: + description: The validator that should be used to verify this datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /datatypes/{name}/{version}: + get: + description: Gets a datatype by its name and version + operationId: getDatatypeByName + parameters: + - description: The name of the datatype + in: path + name: name + required: true + schema: + type: string + - description: The version of the datatype + in: path + name: version + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /events: + get: + description: Gets a list of events + operationId: getEvents + parameters: + - description: When set, the API will return the record that this item references + in its 'reference' field + in: query + name: fetchreferences + schema: + example: "true" + type: string + - description: When set, the API will return the record that this item references + in its 'reference' field + in: query + name: fetchreference + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: correlator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: reference + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part + of. Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /events/{eid}: + get: + description: Gets an event by its ID + operationId: getEventByID + parameters: + - description: The event ID + in: path + name: eid + required: true + schema: + type: string + - description: When set, the API will return the record that this item references + in its 'reference' field + in: query + name: fetchreference + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part of. + Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /groups: + get: + description: Gets a list of groups + operationId: getGroups + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: ledger + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time when the group was first used to send + a message in the network + format: date-time + type: string + hash: + description: The identifier hash of this group. Derived from + the name and group members + format: byte + type: string + localNamespace: + description: The local namespace of the group + type: string + members: + description: The list of members in this privacy group + items: + description: The list of members in this privacy group + properties: + identity: + description: The DID of the group member + type: string + node: + description: The UUID of the node that receives a copy + of the off-chain message for the identity + format: uuid + type: string + type: object + type: array + message: + description: The message used to broadcast this group privately + to the members + format: uuid + type: string + name: + description: The optional name of the group, allowing multiple + unique groups to exist with the same list of recipients + type: string + namespace: + description: The namespace of the group within the multiparty + network + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /groups/{hash}: + get: + description: Gets a group by its ID (hash) + operationId: getGroupByHash + parameters: + - description: The hash of the group + in: path + name: hash + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time when the group was first used to send a + message in the network + format: date-time + type: string + hash: + description: The identifier hash of this group. Derived from the + name and group members + format: byte + type: string + localNamespace: + description: The local namespace of the group + type: string + members: + description: The list of members in this privacy group + items: + description: The list of members in this privacy group + properties: + identity: + description: The DID of the group member + type: string + node: + description: The UUID of the node that receives a copy of + the off-chain message for the identity + format: uuid + type: string + type: object + type: array + message: + description: The message used to broadcast this group privately + to the members + format: uuid + type: string + name: + description: The optional name of the group, allowing multiple + unique groups to exist with the same list of recipients + type: string + namespace: + description: The namespace of the group within the multiparty + network + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /identities: + get: + description: Gets a list of all identities that have been registered in the + namespace + operationId: getIdentities + parameters: + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to + prove data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum + address, or Fabric MSP identifier + type: string + type: object + type: array + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Registers a new identity in the network + operationId: postNewIdentity + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + key: + description: The blockchain signing key to use to make the claim + to the identity. Must be available to the local node to sign the + identity claim. Will become a verifier on the established identity + type: string + name: + description: The name of the identity. The name must be unique within + the type and namespace + type: string + parent: + description: On input the parent can be specified directly as the + UUID of and existing identity, or as a DID to resolve to that + identity, or an organization name. The parent must already have + been registered, and its blockchain signing key must be available + to the local node to sign the verification + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /identities/{did}: + get: + description: Gets an identity by its DID + operationId: getIdentityByDID + parameters: + - description: The identity DID + in: path + name: did + required: true + schema: + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, that + have been bound to this identity and can be used to prove data + orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /identities/{iid}: + get: + description: Gets an identity by its ID + operationId: getIdentityByID + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + example: id + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + patch: + description: Updates an identity + operationId: patchUpdateIdentity + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /identities/{iid}/did: + get: + description: Gets the DID for an identity based on its ID + operationId: getIdentityDID + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + example: id + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + '@context': + description: See https://www.w3.org/TR/did-core/#json-ld + items: + description: See https://www.w3.org/TR/did-core/#json-ld + type: string + type: array + authentication: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + type: array + id: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + verificationMethod: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + properties: + blockchainAcountId: + description: For blockchains like Ethereum that represent + signing identities directly by their public key summarized + in an account string + type: string + controller: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + dataExchangePeerID: + description: A string provided by your Data Exchange plugin, + that it uses a technology specific mechanism to validate + against when messages arrive from this identity + type: string + id: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + mspIdentityString: + description: For Hyperledger Fabric where the signing identity + is represented by an MSP identifier (containing X509 certificate + DN strings) that were validated by your local MSP + type: string + type: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /identities/{iid}/verifiers: + get: + description: Gets the verifiers for an identity + operationId: getIdentityVerifiers + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + example: id + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: identity + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: value + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time this verifier was created on this node + format: date-time + type: string + hash: + description: Hash used as a globally consistent identifier for + this namespace + type + value combination on every node in + the network + format: byte + type: string + identity: + description: The UUID of the parent identity that has claimed + this verifier + format: uuid + type: string + namespace: + description: The namespace of the verifier + type: string + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /messages: + get: + description: Gets a list of messages + operationId: getMsgs + parameters: + - description: Fetch the data and include it in the messages returned + in: query + name: fetchdata + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + batch: + description: The UUID of the batch in which the message was + pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the + message. Derived from the array of data ids+hashes attached + to this message + format: byte + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce + is assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/{msgid}: + get: + description: Gets a message by its ID + operationId: getMsgByID + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: Fetch the data and include it in the messages returned + in: query + name: fetchdata + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + properties: + blob: + description: An optional in-line hash reference to a previously + uploaded binary data blob + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached + to the blob, commonly used as a path/filename, and + indexed for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will be + picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/{msgid}/data: + get: + description: Gets the list of data items that are attached to a message + operationId: getMsgData + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the + value and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/{msgid}/events: + get: + description: Gets the list of events for a message + operationId: getMsgEvents + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: correlator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: reference + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part + of. Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/{msgid}/transaction: + get: + description: Gets the transaction for a message + operationId: getMsgTxn + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + blockchainIds: + description: 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 + items: + description: 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 + type: string + type: array + created: + description: 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 + format: date-time + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + idempotencyKey: + description: An optional unique identifier for a transaction. + Cannot be duplicated within a namespace, thus allowing idempotent + submission of transactions to the API + type: string + namespace: + description: The namespace of the FireFly transaction + type: string + type: + description: The type of the FireFly transaction + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/broadcast: + post: + description: Broadcasts a message to all members in the network + operationId: postNewMessageBroadcast + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation of + the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON + type - object, array, string, number or boolean + type: object + type: array + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the message + to the applications that process it + type: string + topics: + description: A message topic associates this message with an + ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver this + message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/private: + post: + description: Privately sends a message to one or more members in the network + operationId: postNewMessagePrivate + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation of + the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON + type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive a + copy of the off-chain message for the identity. The + first applicable node for the identity will be picked + automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list of + the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the message + to the applications that process it + type: string + topics: + description: A message topic associates this message with an + ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver this + message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /messages/requestreply: + post: + description: Sends a message with a blocking HTTP request, waits for a reply + to that message, then sends the reply as the HTTP response. + operationId: postNewMessageRequestReply + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation of + the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON + type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive a + copy of the off-chain message for the identity. The + first applicable node for the identity will be picked + automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list of + the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the message + to the applications that process it + type: string + topics: + description: A message topic associates this message with an + ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver this + message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + properties: + blob: + description: An optional in-line hash reference to a previously + uploaded binary data blob + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached + to the blob, commonly used as a path/filename, and + indexed for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will be + picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /namespaces: + get: + description: Gets a list of namespaces + operationId: getNamespaces + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the namespace was created + format: date-time + type: string + description: + description: A description of the namespace + type: string + name: + description: The local namespace name + type: string + networkName: + description: The shared namespace name within the multiparty + network + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Global + /namespaces/{ns}: + get: + description: Gets a namespace + operationId: getNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the namespace was created + format: date-time + type: string + description: + description: A description of the namespace + type: string + name: + description: The local namespace name + type: string + networkName: + description: The shared namespace name within the multiparty network + type: string + type: object + description: Success + default: + description: "" + tags: + - Global + /namespaces/{ns}/apis: + get: + description: Gets a list of contract APIs that have been published + operationId: getContractAPIsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used + to publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the + API + type: string + namespace: + description: The namespace of the contract API + type: string + urls: + description: The URLs to use to access the API + properties: + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates and broadcasts a new custom smart contract API + operationId: postNewContractAPINamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + name: + description: The name that is used in the URL to access the API + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + urls: + description: The URLs to use to access the API + properties: + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + urls: + description: The URLs to use to access the API + properties: + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/apis/{apiName}: + get: + description: Gets information about a contract API, including the URLs for the + OpenAPI Spec and Swagger UI for the API + operationId: getContractAPIByNameNamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + urls: + description: The URLs to use to access the API + properties: + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/apis/{apiName}/interface: + get: + description: Gets a contract interface for a contract API + operationId: getContractAPIInterfaceNamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/apis/{apiName}/invoke/{methodPath}: + post: + description: Invokes a method on a smart contract API. Performs a blockchain + transaction. + operationId: postContractAPIInvokeNamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a method on a smart + contract + in: path + name: methodPath + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + errors: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + items: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + interface: + description: The UUID of a method within a pre-configured FireFly + interface (FFI) definition for a smart contract. Required if the + 'method' is omitted. Also see Contract APIs as a way to configure + a dedicated API for your FFI, including all methods and an OpenAPI/Swagger + interface + format: uuid + type: string + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + method: + description: An in-line FFI method definition for the method to + invoke. Required when FFI is not specified + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + methodPath: + description: The pathname of the method on the specified FFI + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/apis/{apiName}/listeners/{eventPath}: + get: + description: Gets a list of contract listeners + operationId: getContractAPIListenersNamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a event on a smart + contract + in: path + name: eventPath + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: backendid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: location + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: signature + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: The definition of the event, either provided in-line + when creating the listener, or extracted from the referenced + FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For + example an Ethereum contract address, or a Fabric chaincode + name and channel + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: The stringified signature of the event, as computed + by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates a new blockchain listener for events emitted by custom + smart contracts + operationId: postContractAPIListenersNamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a event on a smart + contract + in: path + name: eventPath + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + event: + description: The definition of the event, either provided in-line + when creating the listener, or extracted from the referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + name: + description: A descriptive name for the listener + type: string + options: + description: Options that control how the listener subscribes to + events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + topic: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: The definition of the event, either provided in-line + when creating the listener, or extracted from the referenced + FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and + channel + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: The stringified signature of the event, as computed + by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/apis/{apiName}/query/{methodPath}: + post: + description: Queries a method on a smart contract API. Performs a read-only + query. + operationId: postContractAPIQueryNamespace + parameters: + - description: The name of the contract API + in: path + name: apiName + required: true + schema: + type: string + - description: The name or uniquely generated path name of a method on a smart + contract + in: path + name: methodPath + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + errors: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + items: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + interface: + description: The UUID of a method within a pre-configured FireFly + interface (FFI) definition for a smart contract. Required if the + 'method' is omitted. Also see Contract APIs as a way to configure + a dedicated API for your FFI, including all methods and an OpenAPI/Swagger + interface + format: uuid + type: string + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + method: + description: An in-line FFI method definition for the method to + invoke. Required when FFI is not specified + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + methodPath: + description: The pathname of the method on the specified FFI + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + additionalProperties: {} + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/apis/{id}: + put: + description: The ID of the contract API + operationId: putContractAPINamespace + parameters: + - description: The name of the contract API + in: path + name: id + required: true + schema: + example: id + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + name: + description: The name that is used in the URL to access the API + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + urls: + description: The URLs to use to access the API + properties: + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + id: + description: The UUID of the contract API + format: uuid + type: string + interface: + description: Reference to the FireFly Interface definition associated + with the contract API + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: 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 + message: + description: The UUID of the broadcast message that was used to + publish this API to the network + format: uuid + type: string + name: + description: The name that is used in the URL to access the API + type: string + namespace: + description: The namespace of the contract API + type: string + urls: + description: The URLs to use to access the API + properties: + openapi: + description: The URL to download the OpenAPI v3 (Swagger) + description for the API generated in JSON or YAML format + type: string + ui: + description: The URL to use in a web browser to access the + SwaggerUI explorer/exerciser for the API + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/batches: + get: + description: Gets a list of message batches + operationId: getBatchesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: node + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: payloadref + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + author: + description: The DID of identity of the submitter + type: string + confirmed: + description: The time when the batch was confirmed + format: date-time + type: string + created: + description: The time the batch was sealed + format: date-time + type: string + group: + description: The privacy group the batch is sent to, for private + batches + format: byte + type: string + hash: + description: The hash of the manifest of the batch + format: byte + type: string + id: + description: The UUID of the batch + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + manifest: + description: The manifest of the batch + namespace: + description: The namespace of the batch + type: string + node: + description: The UUID of the node that generated the batch + format: uuid + type: string + tx: + description: The FireFly transaction associated with this batch + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of the batch + enum: + - broadcast + - private + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/batches/{batchid}: + get: + description: Gets a message batch + operationId: getBatchByIDNamespace + parameters: + - description: The batch ID + in: path + name: batchid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + author: + description: The DID of identity of the submitter + type: string + confirmed: + description: The time when the batch was confirmed + format: date-time + type: string + created: + description: The time the batch was sealed + format: date-time + type: string + group: + description: The privacy group the batch is sent to, for private + batches + format: byte + type: string + hash: + description: The hash of the manifest of the batch + format: byte + type: string + id: + description: The UUID of the batch + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + manifest: + description: The manifest of the batch + namespace: + description: The namespace of the batch + type: string + node: + description: The UUID of the node that generated the batch + format: uuid + type: string + tx: + description: The FireFly transaction associated with this batch + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of the batch + enum: + - broadcast + - private + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/blockchainevents: + get: + description: Gets a list of blockchain events + operationId: getBlockchainEventsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: listener + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: protocolid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: source + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: timestamp + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.blockchainid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + id: + description: The UUID assigned to the event by FireFly + format: uuid + type: string + info: + additionalProperties: + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + type: object + listener: + description: The UUID of the listener that detected this event, + or nil for built-in events in the system namespace + format: uuid + type: string + name: + description: The name of the event in the blockchain smart contract + type: string + namespace: + description: The namespace of the listener that detected this + blockchain event + type: string + output: + additionalProperties: + description: The data output by the event, parsed to JSON + according to the interface of the smart contract + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + type: object + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely on the blockchain (convention for plugins + is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) + type: string + source: + description: The blockchain plugin or token service that detected + the event + type: string + timestamp: + description: The time allocated to this event by the blockchain. + This is the block timestamp for most blockchain connectors + format: date-time + type: string + tx: + description: 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 + properties: + blockchainId: + description: The blockchain transaction ID, in the format + specific to the blockchain involved in the transaction. + Not all FireFly transactions include a blockchain + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/blockchainevents/{id}: + get: + description: Gets a blockchain event + operationId: getBlockchainEventByIDNamespace + parameters: + - description: The blockchain event ID + in: path + name: id + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + id: + description: The UUID assigned to the event by FireFly + format: uuid + type: string + info: + additionalProperties: + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + description: Detailed blockchain specific information about the + event, as generated by the blockchain connector + type: object + listener: + description: The UUID of the listener that detected this event, + or nil for built-in events in the system namespace + format: uuid + type: string + name: + description: The name of the event in the blockchain smart contract + type: string + namespace: + description: The namespace of the listener that detected this + blockchain event + type: string + output: + additionalProperties: + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + type: object + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely on the blockchain (convention for plugins + is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) + type: string + source: + description: The blockchain plugin or token service that detected + the event + type: string + timestamp: + description: The time allocated to this event by the blockchain. + This is the block timestamp for most blockchain connectors + format: date-time + type: string + tx: + description: 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 + properties: + blockchainId: + description: The blockchain transaction ID, in the format + specific to the blockchain involved in the transaction. + Not all FireFly transactions include a blockchain + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/charts/histogram/{collection}: + get: + description: Gets a JSON object containing statistics data that can be used + to build a graphical representation of recent activity in a given database + collection + operationId: getChartHistogramNamespace + parameters: + - description: The collection ID + in: path + name: collection + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Start time of the data to be fetched + in: query + name: startTime + schema: + type: string + - description: End time of the data to be fetched + in: query + name: endTime + schema: + type: string + - description: Number of buckets between start time and end time + in: query + name: buckets + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + count: + description: Total count of entries in this time bucket within + the histogram + type: string + isCapped: + description: Indicates whether there are more results in this + bucket that are not being displayed + type: boolean + timestamp: + description: Starting timestamp for the bucket + format: date-time + type: string + types: + description: Array of separate counts for individual types of + record within the bucket + items: + description: Array of separate counts for individual types + of record within the bucket + properties: + count: + description: Count of entries of a given type within a + bucket + type: string + type: + description: Name of the type + type: string + type: object + type: array + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/deploy: + post: + description: Deploy a new smart contract + operationId: postContractDeployNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + contract: + description: The smart contract to deploy. This should be pre-compiled + if required by the blockchain connector + definition: + description: The definition of the smart contract + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + description: An optional array of inputs passed to the smart contract's + constructor, if applicable + items: + description: An optional array of inputs passed to the smart contract's + constructor, if applicable + type: array + key: + description: The blockchain signing key that will be used to deploy + the contract. Defaults to the first signing key of the organization + that operates the node + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/interfaces: + get: + description: Gets a list of contract interfaces that have been published + operationId: getContractInterfacesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: version + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used + by the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used + to publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used + by the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart + contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates and broadcasts a new custom smart contract interface + operationId: postNewContractInterfaceNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart contract + name + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/interfaces/{interfaceId}: + get: + description: Gets a contract interface by its ID + operationId: getContractInterfaceNamespace + parameters: + - description: The ID of the contract interface + in: path + name: interfaceId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the full FireFly Interface document + including all methods, events, and parameters + in: query + name: fetchchildren + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/interfaces/{name}/{version}: + get: + description: Gets a contract interface by its name and version + operationId: getContractInterfaceByNameAndVersionNamespace + parameters: + - description: The name of the contract interface + in: path + name: name + required: true + schema: + type: string + - description: The version of the contract interface + in: path + name: version + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the full FireFly Interface document + including all methods, events, and parameters + in: query + name: fetchchildren + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/interfaces/generate: + post: + description: A convenience method to convert a blockchain specific smart contract + format into a FireFly Interface format. The specific blockchain plugin in + use must support this functionality. + operationId: postGenerateContractInterfaceNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: The description of the FFI to be generated. Defaults + to the description extracted by the blockchain specific converter + utility + type: string + input: + description: A blockchain connector specific payload. For example + in Ethereum this is a JSON structure containing an 'abi' array, + and optionally a 'devdocs' array. + name: + description: The name of the FFI to generate + type: string + namespace: + description: The namespace into which the FFI will be generated + type: string + version: + description: The version of the FFI to generate + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + description: + description: A description of the smart contract this FFI represents + type: string + errors: + description: An array of smart contract error definitions + items: + description: An array of smart contract error definitions + properties: + description: + description: A description of the smart contract error + type: string + id: + description: The UUID of the FFI error definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this error is part of + format: uuid + type: string + name: + description: The name of the error + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: The unique name allocated to this error within + the FFI for use on URL paths + type: string + signature: + description: The stringified signature of the error, as + computed by the blockchain plugin + type: string + type: object + type: array + events: + description: An array of smart contract event definitions + items: + description: An array of smart contract event definitions + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI event definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this event is part of + format: uuid + type: string + name: + description: The name of the event + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + signature: + description: The stringified signature of the event, as + computed by the blockchain plugin + type: string + type: object + type: array + id: + description: The UUID of the FireFly interface (FFI) smart contract + definition + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this FFI to the network + format: uuid + type: string + methods: + description: An array of smart contract method definitions + items: + description: An array of smart contract method definitions + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this method from the original smart contract. Used by + the blockchain plugin and for documentation generation. + type: object + id: + description: The UUID of the FFI method definition + format: uuid + type: string + interface: + description: The UUID of the FFI smart contract definition + that this method is part of + format: uuid + type: string + name: + description: The name of the method + type: string + namespace: + description: The namespace of the FFI + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + pathname: + description: 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 + type: string + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + name: + description: The name of the FFI - usually matching the smart + contract name + type: string + namespace: + description: The namespace of the FFI + type: string + version: + description: A version for the FFI - use of semantic versioning + such as 'v1.0.1' is encouraged + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/invoke: + post: + description: Invokes a method on a smart contract. Performs a blockchain transaction. + operationId: postContractInvokeNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + errors: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + items: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + interface: + description: The UUID of a method within a pre-configured FireFly + interface (FFI) definition for a smart contract. Required if the + 'method' is omitted. Also see Contract APIs as a way to configure + a dedicated API for your FFI, including all methods and an OpenAPI/Swagger + interface + format: uuid + type: string + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + method: + description: An in-line FFI method definition for the method to + invoke. Required when FFI is not specified + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + methodPath: + description: The pathname of the method on the specified FFI + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/listeners: + get: + description: Gets a list of contract listeners + operationId: getContractListenersNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: backendid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: interface + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: location + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: signature + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: The definition of the event, either provided in-line + when creating the listener, or extracted from the referenced + FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by + the blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that + parameters must be ordered correctly on the FFI, + according to the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For + example an Ethereum contract address, or a Fabric chaincode + name and channel + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: The stringified signature of the event, as computed + by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates a new blockchain listener for events emitted by custom + smart contracts + operationId: postNewContractListenerNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + event: + description: The definition of the event, either provided in-line + when creating the listener, or extracted from the referenced FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + eventPath: + description: When creating a listener from an existing FFI, this + is the pathname of the event on that FFI to be detected by this + listener + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + name: + description: A descriptive name for the listener + type: string + options: + description: Options that control how the listener subscribes to + events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + topic: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: The definition of the event, either provided in-line + when creating the listener, or extracted from the referenced + FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and + channel + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: The stringified signature of the event, as computed + by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/listeners/{nameOrId}: + delete: + description: Deletes a contract listener referenced by its name or its ID + operationId: deleteContractListenerNamespace + parameters: + - description: The contract listener name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Non-Default Namespace + get: + description: Gets a contract listener by its name or ID + operationId: getContractListenerByNameOrIDNamespace + parameters: + - description: The contract listener name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return additional status information if + available + in: query + name: fetchstatus + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + backendId: + description: An ID assigned by the blockchain connector to this + listener + type: string + created: + description: The creation time of the listener + format: date-time + type: string + event: + description: The definition of the event, either provided in-line + when creating the listener, or extracted from the referenced + FFI + properties: + description: + description: A description of the smart contract event + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about + this event from the original smart contract. Used by the + blockchain plugin and for documentation generation. + description: Additional blockchain specific fields about this + event from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the event + type: string + params: + description: An array of event parameter/argument definitions + items: + description: An array of event parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + id: + description: The UUID of the smart contract listener + format: uuid + type: string + interface: + description: A reference to an existing FFI, containing pre-registered + type information for the event + properties: + id: + description: The UUID of the FireFly interface + format: uuid + type: string + name: + description: The name of the FireFly interface + type: string + version: + description: The version of the FireFly interface + type: string + type: object + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and + channel + name: + description: A descriptive name for the listener + type: string + namespace: + description: The namespace of the listener, which defines the + namespace of all blockchain events detected by this listener + type: string + options: + description: Options that control how the listener subscribes + to events from the underlying blockchain + properties: + firstEvent: + description: 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' + type: string + type: object + signature: + description: The stringified signature of the event, as computed + by the blockchain plugin + type: string + topic: + description: 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 + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/contracts/query: + post: + description: Queries a method on a smart contract. Performs a read-only query. + operationId: postContractQueryNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + errors: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + items: + description: An in-line FFI errors definition for the method to + invoke. Alternative to specifying FFI + properties: + description: + description: A description of the smart contract error + type: string + name: + description: The name of the error + type: string + params: + description: An array of error parameter/argument definitions + items: + description: An array of error parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to + the order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + type: array + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + input: + additionalProperties: + description: A map of named inputs. The name and type of each + input must be compatible with the FFI description of the method, + so that FireFly knows how to serialize it to the blockchain + via the connector + description: A map of named inputs. The name and type of each input + must be compatible with the FFI description of the method, so + that FireFly knows how to serialize it to the blockchain via the + connector + type: object + interface: + description: The UUID of a method within a pre-configured FireFly + interface (FFI) definition for a smart contract. Required if the + 'method' is omitted. Also see Contract APIs as a way to configure + a dedicated API for your FFI, including all methods and an OpenAPI/Swagger + interface + format: uuid + type: string + key: + description: The blockchain signing key that will sign the invocation. + Defaults to the first signing key of the organization that operates + the node + type: string + location: + description: A blockchain specific contract identifier. For example + an Ethereum contract address, or a Fabric chaincode name and channel + method: + description: An in-line FFI method definition for the method to + invoke. Required when FFI is not specified + properties: + description: + description: A description of the smart contract method + type: string + details: + additionalProperties: + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + description: Additional blockchain specific fields about this + method from the original smart contract. Used by the blockchain + plugin and for documentation generation. + type: object + name: + description: The name of the method + type: string + params: + description: An array of method parameter/argument definitions + items: + description: An array of method parameter/argument definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + returns: + description: An array of method return definitions + items: + description: An array of method return definitions + properties: + name: + description: The name of the parameter. Note that parameters + must be ordered correctly on the FFI, according to the + order in the blockchain smart contract + type: string + schema: + description: 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 + type: object + type: array + type: object + methodPath: + description: The pathname of the method on the specified FFI + type: string + options: + additionalProperties: + description: A map of named inputs that will be passed through + to the blockchain connector + description: A map of named inputs that will be passed through to + the blockchain connector + type: object + type: object + responses: + "200": + content: + application/json: + schema: + additionalProperties: {} + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data: + get: + description: Gets a list of data items + operationId: getDataNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.public + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blob.size + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datatype.name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datatype.version + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: public + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: validator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: value + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the + value and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates a new data item in this FireFly node + operationId: postDataNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + datatype: + description: The optional datatype to use for validation of the + in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON type + - object, array, string, number or boolean + type: object + multipart/form-data: + schema: + properties: + autometa: + description: Success + type: string + datatype.name: + description: Success + type: string + datatype.version: + description: Success + type: string + filename.ext: + format: binary + type: string + metadata: + description: Success + type: string + validator: + description: Success + type: string + type: object + responses: + "201": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data/{dataid}: + get: + description: Gets a data item by its ID, including metadata about this item + operationId: getDataByIDNamespace + parameters: + - description: The data item ID + in: path + name: dataid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data/{dataid}/blob: + get: + description: Downloads the original file that was previously uploaded or received + operationId: getDataBlobNamespace + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + format: byte + type: string + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data/{dataid}/blob/publish: + post: + description: Publishes the binary blob attachment stored in your local data + exchange, to shared storage + operationId: postDataBlobPublishNamespace + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data/{dataid}/messages: + get: + description: Gets a list of the messages associated with a data item + operationId: getDataMsgsNamespace + parameters: + - description: The data item ID + in: path + name: dataid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data/{dataid}/value: + get: + description: Downloads the JSON value of the data resource, without the associated + metadata + operationId: getDataValueNamespace + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + format: byte + type: string + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/data/{dataid}/value/publish: + post: + description: Publishes the JSON value from the specified data resource, to shared + storage + operationId: postDataValuePublishNamespace + parameters: + - description: The blob ID + in: path + name: dataid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the value + and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/datatypes: + get: + description: Gets a list of datatypes that have been published + operationId: getDatatypesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: validator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: version + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used + to publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions + can exist with the same name. Use of semantic versioning is + encourages, such as v1.0.1 + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates and broadcasts a new datatype + operationId: postNewDatatypeNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + name: + description: The name of the datatype + type: string + validator: + description: The validator that should be used to verify this datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/datatypes/{name}/{version}: + get: + description: Gets a datatype by its name and version + operationId: getDatatypeByNameNamespace + parameters: + - description: The name of the datatype + in: path + name: name + required: true + schema: + type: string + - description: The version of the datatype + in: path + name: version + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the datatype was created + format: date-time + type: string + hash: + description: 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 + format: byte + type: string + id: + description: The UUID of the datatype + format: uuid + type: string + message: + description: The UUID of the broadcast message that was used to + publish this datatype to the network + format: uuid + type: string + name: + description: The name of the datatype + type: string + namespace: + description: The namespace of the datatype. Data resources can + only be created referencing datatypes in the same namespace + type: string + validator: + description: The validator that should be used to verify this + datatype + enum: + - json + - none + - definition + type: string + value: + description: The definition of the datatype, in the syntax supported + by the validator (such as a JSON Schema definition) + version: + description: The version of the datatype. Multiple versions can + exist with the same name. Use of semantic versioning is encourages, + such as v1.0.1 + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/events: + get: + description: Gets a list of events + operationId: getEventsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the record that this item references + in its 'reference' field + in: query + name: fetchreferences + schema: + example: "true" + type: string + - description: When set, the API will return the record that this item references + in its 'reference' field + in: query + name: fetchreference + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: correlator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: reference + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part + of. Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/events/{eid}: + get: + description: Gets an event by its ID + operationId: getEventByIDNamespace + parameters: + - description: The event ID + in: path + name: eid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the record that this item references + in its 'reference' field + in: query + name: fetchreference + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part of. + Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/groups: + get: + description: Gets a list of groups + operationId: getGroupsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: ledger + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time when the group was first used to send + a message in the network + format: date-time + type: string + hash: + description: The identifier hash of this group. Derived from + the name and group members + format: byte + type: string + localNamespace: + description: The local namespace of the group + type: string + members: + description: The list of members in this privacy group + items: + description: The list of members in this privacy group + properties: + identity: + description: The DID of the group member + type: string + node: + description: The UUID of the node that receives a copy + of the off-chain message for the identity + format: uuid + type: string + type: object + type: array + message: + description: The message used to broadcast this group privately + to the members + format: uuid + type: string + name: + description: The optional name of the group, allowing multiple + unique groups to exist with the same list of recipients + type: string + namespace: + description: The namespace of the group within the multiparty + network + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/groups/{hash}: + get: + description: Gets a group by its ID (hash) + operationId: getGroupByHashNamespace + parameters: + - description: The hash of the group + in: path + name: hash + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time when the group was first used to send a + message in the network + format: date-time + type: string + hash: + description: The identifier hash of this group. Derived from the + name and group members + format: byte + type: string + localNamespace: + description: The local namespace of the group + type: string + members: + description: The list of members in this privacy group + items: + description: The list of members in this privacy group + properties: + identity: + description: The DID of the group member + type: string + node: + description: The UUID of the node that receives a copy of + the off-chain message for the identity + format: uuid + type: string + type: object + type: array + message: + description: The message used to broadcast this group privately + to the members + format: uuid + type: string + name: + description: The optional name of the group, allowing multiple + unique groups to exist with the same list of recipients + type: string + namespace: + description: The namespace of the group within the multiparty + network + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/identities: + get: + description: Gets a list of all identities that have been registered in the + namespace + operationId: getIdentitiesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to + prove data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum + address, or Fabric MSP identifier + type: string + type: object + type: array + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Registers a new identity in the network + operationId: postNewIdentityNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + key: + description: The blockchain signing key to use to make the claim + to the identity. Must be available to the local node to sign the + identity claim. Will become a verifier on the established identity + type: string + name: + description: The name of the identity. The name must be unique within + the type and namespace + type: string + parent: + description: On input the parent can be specified directly as the + UUID of and existing identity, or as a DID to resolve to that + identity, or an organization name. The parent must already have + been registered, and its blockchain signing key must be available + to the local node to sign the verification + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/identities/{did}: + get: + description: Gets an identity by its DID + operationId: getIdentityByDIDNamespace + parameters: + - description: The identity DID + in: path + name: did + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, that + have been bound to this identity and can be used to prove data + orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/identities/{iid}: + get: + description: Gets an identity by its ID + operationId: getIdentityByIDNamespace + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + example: id + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + patch: + description: Updates an identity + operationId: patchUpdateIdentityNamespace + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/identities/{iid}/did: + get: + description: Gets the DID for an identity based on its ID + operationId: getIdentityDIDNamespace + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + example: id + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + '@context': + description: See https://www.w3.org/TR/did-core/#json-ld + items: + description: See https://www.w3.org/TR/did-core/#json-ld + type: string + type: array + authentication: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + type: array + id: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + verificationMethod: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + properties: + blockchainAcountId: + description: For blockchains like Ethereum that represent + signing identities directly by their public key summarized + in an account string + type: string + controller: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + dataExchangePeerID: + description: A string provided by your Data Exchange plugin, + that it uses a technology specific mechanism to validate + against when messages arrive from this identity + type: string + id: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + mspIdentityString: + description: For Hyperledger Fabric where the signing identity + is represented by an MSP identifier (containing X509 certificate + DN strings) that were validated by your local MSP + type: string + type: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/identities/{iid}/verifiers: + get: + description: Gets the verifiers for an identity + operationId: getIdentityVerifiersNamespace + parameters: + - description: The identity ID, which is a UUID generated by FireFly + in: path + name: iid + required: true + schema: + example: id + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: identity + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: value + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time this verifier was created on this node + format: date-time + type: string + hash: + description: Hash used as a globally consistent identifier for + this namespace + type + value combination on every node in + the network + format: byte + type: string + identity: + description: The UUID of the parent identity that has claimed + this verifier + format: uuid + type: string + namespace: + description: The namespace of the verifier + type: string + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages: + get: + description: Gets a list of messages + operationId: getMsgsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Fetch the data and include it in the messages returned + in: query + name: fetchdata + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: author + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: cid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: confirmed + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: datahash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: group + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pins + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tag + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topics + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: txtype + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + batch: + description: The UUID of the batch in which the message was + pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are + used to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this + when a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the + message. Derived from the array of data ids+hashes attached + to this message + format: byte + type: string + group: + description: Private messages only - the identifier hash + of the privacy group. Derived from the name and member + list of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be + assigned - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce + is assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/{msgid}: + get: + description: Gets a message by its ID + operationId: getMsgByIDNamespace + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Fetch the data and include it in the messages returned + in: query + name: fetchdata + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + properties: + blob: + description: An optional in-line hash reference to a previously + uploaded binary data blob + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached + to the blob, commonly used as a path/filename, and + indexed for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will be + picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/{msgid}/data: + get: + description: Gets the list of data items that are attached to a message + operationId: getMsgDataNamespace + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + blob: + description: An optional hash reference to a binary blob attachment + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached to + the blob, commonly used as a path/filename, and indexed + for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + created: + description: The creation time of the data resource + format: date-time + type: string + datatype: + description: The optional datatype to use of validation of this + data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the data resource. Derived from the + value and the hash of any binary blob attachment + format: byte + type: string + id: + description: The UUID of the data resource + format: uuid + type: string + namespace: + description: The namespace of the data resource + type: string + public: + description: 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.) + type: string + validator: + description: The data validator type + type: string + value: + description: 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 + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/{msgid}/events: + get: + description: Gets the list of events for a message + operationId: getMsgEventsNamespace + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: correlator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: reference + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: topic + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + correlator: + description: 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 + format: uuid + type: string + created: + description: 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 + format: date-time + type: string + id: + description: The UUID assigned to this event by your local FireFly + node + format: uuid + type: string + namespace: + description: The namespace of the event. Your application must + subscribe to events within a namespace + type: string + reference: + description: 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 + format: uuid + type: string + sequence: + description: 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) + format: int64 + type: integer + topic: + description: 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 + type: string + tx: + description: The UUID of a transaction that is event is part + of. Not all events are part of a transaction + format: uuid + type: string + type: + description: 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 + enum: + - transaction_submitted + - message_confirmed + - message_rejected + - datatype_confirmed + - identity_confirmed + - identity_updated + - token_pool_confirmed + - token_pool_op_failed + - token_transfer_confirmed + - token_transfer_op_failed + - token_approval_confirmed + - token_approval_op_failed + - contract_interface_confirmed + - contract_api_confirmed + - blockchain_event_received + - blockchain_invoke_op_succeeded + - blockchain_invoke_op_failed + - blockchain_contract_deploy_op_succeeded + - blockchain_contract_deploy_op_failed + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/{msgid}/transaction: + get: + description: Gets the transaction for a message + operationId: getMsgTxnNamespace + parameters: + - description: The message ID + in: path + name: msgid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + blockchainIds: + description: 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 + items: + description: 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 + type: string + type: array + created: + description: 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 + format: date-time + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + idempotencyKey: + description: An optional unique identifier for a transaction. + Cannot be duplicated within a namespace, thus allowing idempotent + submission of transactions to the API + type: string + namespace: + description: The namespace of the FireFly transaction + type: string + type: + description: The type of the FireFly transaction + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/broadcast: + post: + description: Broadcasts a message to all members in the network + operationId: postNewMessageBroadcastNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation of + the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON + type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive a + copy of the off-chain message for the identity. The + first applicable node for the identity will be picked + automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list of + the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the message + to the applications that process it + type: string + topics: + description: A message topic associates this message with an + ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver this + message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/private: + post: + description: Privately sends a message to one or more members in the network + operationId: postNewMessagePrivateNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation of + the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON + type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive a + copy of the off-chain message for the identity. The + first applicable node for the identity will be picked + automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list of + the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the message + to the applications that process it + type: string + topics: + description: A message topic associates this message with an + ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver this + message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: The list of data elements attached to the message + items: + description: The list of data elements attached to the message + properties: + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + type: object + type: array + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/messages/requestreply: + post: + description: Sends a message with a blocking HTTP request, waits for a reply + to that message, then sends the reply as the HTTP response. + operationId: postNewMessageRequestReplyNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + properties: + datatype: + description: The optional datatype to use for validation of + the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line data + type: string + value: + description: The in-line value for the data. Can be any JSON + type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive a + copy of the off-chain message for the identity. The + first applicable node for the identity will be picked + automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list of + the group + format: byte + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + tag: + description: The message tag indicates the purpose of the message + to the applications that process it + type: string + topics: + description: A message topic associates this message with an + ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver this + message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The UUID of the batch in which the message was pinned/transferred + format: uuid + type: string + confirmed: + description: The timestamp of when the message was confirmed/rejected + format: date-time + type: string + data: + description: For input allows you to specify data in-line in the + message, that will be turned into data attachments. For output + when fetchdata is used on API calls, includes the in-line data + payloads of all data attachments + items: + description: For input allows you to specify data in-line in + the message, that will be turned into data attachments. For + output when fetchdata is used on API calls, includes the in-line + data payloads of all data attachments + properties: + blob: + description: An optional in-line hash reference to a previously + uploaded binary data blob + properties: + hash: + description: The hash of the binary blob data + format: byte + type: string + name: + description: The name field from the metadata attached + to the blob, commonly used as a path/filename, and + indexed for search + type: string + public: + description: 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.) + type: string + size: + description: The size of the binary data + format: int64 + type: integer + type: object + datatype: + description: The optional datatype to use for validation + of the in-line data + properties: + name: + description: The name of the datatype + type: string + version: + description: The version of the datatype. Semantic versioning + is encouraged, such as v1.0.1 + type: string + type: object + hash: + description: The hash of the referenced data + format: byte + type: string + id: + description: The UUID of the referenced data resource + format: uuid + type: string + validator: + description: The data validator type to use for in-line + data + type: string + value: + description: The in-line value for the data. Can be any + JSON type - object, array, string, number or boolean + type: object + type: array + group: + description: Allows you to specify details of the private group + of recipients in-line in the message. Alternative to using the + header.group to specify the hash of a group that has been previously + resolved + properties: + members: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + items: + description: An array of members of the group. If no identities + local to the sending node are included, then the organization + owner of the local node is added automatically + properties: + identity: + description: The DID of the group member. On input can + be a UUID or org name, and will be resolved to a DID + type: string + node: + description: The UUID of the node that will receive + a copy of the off-chain message for the identity. + The first applicable node for the identity will be + picked automatically on input if not specified + type: string + type: object + type: array + name: + description: Optional name for the group. Allows you to have + multiple separate groups with the same list of participants + type: string + type: object + hash: + description: The hash of the message. Derived from the header, + which includes the data hash + format: byte + type: string + header: + description: The message header contains all fields that are used + to build the message hash + properties: + author: + description: The DID of identity of the submitter + type: string + cid: + description: The correlation ID of the message. Set this when + a message is a response to another message + format: uuid + type: string + created: + description: The creation time of the message + format: date-time + type: string + datahash: + description: A single hash representing all data in the message. + Derived from the array of data ids+hashes attached to this + message + format: byte + type: string + group: + description: Private messages only - the identifier hash of + the privacy group. Derived from the name and member list + of the group + format: byte + type: string + id: + description: The UUID of the message. Unique to each message + format: uuid + type: string + key: + description: The on-chain signing key used to sign the transaction + type: string + namespace: + description: The namespace of the message within the multiparty + network + type: string + tag: + description: The message tag indicates the purpose of the + message to the applications that process it + type: string + topics: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + items: + description: A message topic associates this message with + an ordered stream of data. A custom topic should be assigned + - using the default topic is discouraged + type: string + type: array + txtype: + description: The type of transaction used to order/deliver + this message + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: + description: The type of the message + enum: + - definition + - broadcast + - private + - groupinit + - transfer_broadcast + - transfer_private + - approval_broadcast + - approval_private + type: string + type: object + idempotencyKey: + description: 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 + type: string + localNamespace: + description: The local namespace of the message + type: string + pins: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + items: + description: For private messages, a unique pin hash:nonce is + assigned for each topic + type: string + type: array + state: + description: The current state of the message + enum: + - staged + - ready + - sent + - pending + - confirmed + - rejected + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/action: + post: + description: Notify all nodes in the network of a new governance action + operationId: postNetworkActionNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + type: + description: The action to be performed + enum: + - terminate + type: string + type: object + responses: + "202": + content: + application/json: + schema: + properties: + type: + description: The action to be performed + enum: + - terminate + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/diddocs/{did}: + get: + description: Gets a DID document by its DID + operationId: getNetworkDIDDocByDIDNamespace + parameters: + - description: The identity DID + in: path + name: did + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + '@context': + description: See https://www.w3.org/TR/did-core/#json-ld + items: + description: See https://www.w3.org/TR/did-core/#json-ld + type: string + type: array + authentication: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + type: array + id: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + verificationMethod: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + properties: + blockchainAcountId: + description: For blockchains like Ethereum that represent + signing identities directly by their public key summarized + in an account string + type: string + controller: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + dataExchangePeerID: + description: A string provided by your Data Exchange plugin, + that it uses a technology specific mechanism to validate + against when messages arrive from this identity + type: string + id: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + mspIdentityString: + description: For Hyperledger Fabric where the signing identity + is represented by an MSP identifier (containing X509 certificate + DN strings) that were validated by your local MSP + type: string + type: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/identities: + get: + deprecated: true + description: Gets the list of identities in the network (deprecated - use /identities + instead of /network/identities + operationId: getNetworkIdentitiesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to + prove data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum + address, or Fabric MSP identifier + type: string + type: object + type: array + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/identities/{did}: + get: + deprecated: true + description: Gets an identity by its DID + operationId: getNetworkIdentityByDIDNamespace + parameters: + - description: The identity DID + in: path + name: did + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, that + have been bound to this identity and can be used to prove data + orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/nodes: + get: + description: Gets a list of nodes in the network + operationId: getNetworkNodesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/nodes/{nameOrId}: + get: + description: Gets information about a specific node in the network + operationId: getNetworkNodeNamespace + parameters: + - description: The name or ID of the node + in: path + name: nameOrId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/nodes/self: + post: + description: Instructs this FireFly node to register itself on the network + operationId: postNodesSelfNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + additionalProperties: {} + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/organizations: + get: + description: Gets a list of orgs in the network + operationId: getNetworkOrgsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Registers a new org in the network + operationId: postNewOrganizationNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + key: + description: The blockchain signing key to use to make the claim + to the identity. Must be available to the local node to sign the + identity claim. Will become a verifier on the established identity + type: string + name: + description: The name of the identity. The name must be unique within + the type and namespace + type: string + parent: + description: On input the parent can be specified directly as the + UUID of and existing identity, or as a DID to resolve to that + identity, or an organization name. The parent must already have + been registered, and its blockchain signing key must be available + to the local node to sign the verification + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/organizations/{nameOrId}: + get: + description: Gets information about a specific org in the network + operationId: getNetworkOrgNamespace + parameters: + - description: The name or ID of the org + in: path + name: nameOrId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/network/organizations/self: + post: + description: Instructs this FireFly node to register its org on the network + operationId: postNewOrganizationSelfNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + additionalProperties: {} + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/operations: + get: + description: Gets a a list of operations + operationId: getOpsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: error + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: input + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: output + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: plugin + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: retry + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: status + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for + this operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a + previous operation, this field points to the UUID of the operation + being retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/operations/{opid}: + get: + description: Gets an operation by ID + operationId: getOpByIDNamespace + parameters: + - description: The operation ID key to get + in: path + name: opid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/operations/{opid}/retry: + post: + description: Retries a failed operation + operationId: postOpRetryNamespace + parameters: + - description: The UUID of the operation + in: path + name: opid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + additionalProperties: {} + type: object + responses: + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/pins: + get: + description: Queries the list of pins received from the blockchain + operationId: getPinsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: dispatched + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: index + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: masked + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + batch: + description: The UUID of the batch of messages this pin is part + of + format: uuid + type: string + batchHash: + description: The manifest hash batch of messages this pin is + part of + format: byte + type: string + created: + description: The time the FireFly node created the pin + format: date-time + type: string + dispatched: + description: Once true, this pin has been processed and will + not be processed again + type: boolean + hash: + description: The hash represents a topic within a message in + the batch. If a message has multiple topics, then multiple + pins are created. If the message is private, the hash is masked + for privacy + format: byte + type: string + index: + description: The index of this pin within the batch. One pin + is created for each topic, of each message in the batch + format: int64 + type: integer + masked: + description: True if the pin is for a private message, and hence + is masked with the group ID and salted with a nonce so observers + of the blockchain cannot use pin hash to match this transaction + to other transactions or participants + type: boolean + namespace: + description: The namespace of the pin + type: string + sequence: + description: The order of the pin in the local FireFly database, + which matches the order in which pins were delivered to FireFly + by the blockchain connector event stream + format: int64 + type: integer + signer: + description: The blockchain signing key that submitted this + transaction, as passed through to FireFly by the smart contract + that emitted the blockchain event + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/pins/rewind: + post: + description: Force a rewind of the event aggregator to a previous position, + to re-evaluate all unconfirmed pins since that point + operationId: postPinsRewindNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + batch: + description: The ID of the batch to which the event aggregator should + rewind. Either sequence or batch must be specified + format: uuid + type: string + sequence: + description: The sequence of the pin to which the event aggregator + should rewind. Either sequence or batch must be specified + format: int64 + type: integer + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The ID of the batch to which the event aggregator + should rewind. Either sequence or batch must be specified + format: uuid + type: string + sequence: + description: The sequence of the pin to which the event aggregator + should rewind. Either sequence or batch must be specified + format: int64 + type: integer + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/status: + get: + description: Gets the status of this namespace + operationId: getStatusNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + multiparty: + description: Information about the multi-party system configured + on this namespace + properties: + contract: + description: Information about the multi-party smart contract + configured for this namespace + properties: + active: + description: The currently active FireFly smart contract + properties: + firstEvent: + description: 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 + type: string + index: + description: The index of this contract in the config + file + type: integer + info: + description: Additional info about the current status + of the multi-party contract + properties: + finalEvent: + description: The identifier for the final blockchain + event received from this contract before termination + type: string + subscription: + description: The backend identifier of the subscription + for the FireFly BatchPin contract + type: string + version: + description: The version of this multiparty contract + type: integer + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + type: object + terminated: + description: Previously-terminated FireFly smart contracts + items: + description: Previously-terminated FireFly smart contracts + properties: + firstEvent: + description: 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 + type: string + index: + description: The index of this contract in the config + file + type: integer + info: + description: Additional info about the current status + of the multi-party contract + properties: + finalEvent: + description: The identifier for the final blockchain + event received from this contract before termination + type: string + subscription: + description: The backend identifier of the subscription + for the FireFly BatchPin contract + type: string + version: + description: The version of this multiparty + contract + type: integer + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a + Fabric chaincode name and channel + type: object + type: array + type: object + enabled: + description: Whether multi-party mode is enabled for this + namespace + type: boolean + type: object + namespace: + description: The namespace that this status applies to + properties: + created: + description: The time the namespace was created + format: date-time + type: string + description: + description: A description of the namespace + type: string + name: + description: The local namespace name + type: string + networkName: + description: The shared namespace name within the multiparty + network + type: string + type: object + node: + description: Details of the local node + properties: + id: + description: The UUID of the node, if registered + format: uuid + type: string + name: + description: The name of this node, as specified in the local + configuration + type: string + registered: + description: Whether the node has been successfully registered + type: boolean + type: object + org: + description: Details of the root organization identity registered + for this namespace on the local node + properties: + did: + description: The DID of the organization identity, if registered + type: string + id: + description: The UUID of the organization, if registered + format: uuid + type: string + name: + description: The name of the node operator organization, as + specified in the local configuration + type: string + registered: + description: Whether the organization has been successfully + registered + type: boolean + verifiers: + description: Array of verifiers (blockchain keys) owned by + this identity + items: + description: Array of verifiers (blockchain keys) owned + by this identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum + address, or Fabric MSP identifier + type: string + type: object + type: array + type: object + plugins: + description: Information about plugins configured on this namespace + properties: + blockchain: + description: The blockchain plugins on this namespace + items: + description: The blockchain plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + dataExchange: + description: The data exchange plugins on this namespace + items: + description: The data exchange plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + database: + description: The database plugins on this namespace + items: + description: The database plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + events: + description: The event plugins on this namespace + items: + description: The event plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + identity: + description: The identity plugins on this namespace + items: + description: The identity plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + sharedStorage: + description: The shared storage plugins on this namespace + items: + description: The shared storage plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + tokens: + description: The token plugins on this namespace + items: + description: The token plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + type: object + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/status/batchmanager: + get: + description: Gets the status of the batch manager + operationId: getStatusBatchManagerNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + processors: + description: An array of currently active batch processors + items: + description: An array of currently active batch processors + properties: + dispatcher: + description: The type of dispatcher for this processor + type: string + name: + description: The name of the processor, which includes details + of the attributes of message are allocated to this processor + type: string + status: + description: The flush status for this batch processor + properties: + averageBatchBytes: + description: The average byte size of each batch + format: int64 + type: integer + averageBatchData: + description: The average number of data attachments + included in each batch + format: double + type: number + averageBatchMessages: + description: The average number of messages included + in each batch + format: double + type: number + averageFlushTimeMS: + description: The average amount of time spent flushing + each batch + format: int64 + type: integer + blocked: + description: True if the batch flush is in a retry loop, + due to errors being returned by the plugins + type: boolean + flushing: + description: If a flush is in progress, this is the + UUID of the batch being flushed + format: uuid + type: string + lastFlushError: + description: The last error received by this batch processor + while flushing + type: string + lastFlushErrorTime: + description: The time of the last flush + format: date-time + type: string + lastFlushStartTime: + description: The last time a flush was performed + format: date-time + type: string + totalBatches: + description: The total count of batches flushed by this + processor since it started + format: int64 + type: integer + totalErrors: + description: The total count of error flushed encountered + by this processor since it started + format: int64 + type: integer + type: object + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/subscriptions: + get: + description: Gets a list of subscriptions + operationId: getSubscriptionsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: events + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: filters + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: options + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: transport + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' + instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event + in the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this + filter is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the + subscription + type: string + options: + description: Subscription options + properties: + fastack: + description: 'Webhooks only: When true the event will be + acknowledged before the webhook is invoked, allowing parallel + invocations' + type: boolean + firstEvent: + description: Whether your appplication 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on + the webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + input: + description: 'Webhooks only: A set of options to extract + data from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data + input, to use for the request body. Default is the + whole first body + type: string + headers: + description: A top-level property of the first data + input, to use for headers + type: string + path: + description: A top-level property of the first data + input, to use for a path to append with escaping to + the webhook path + type: string + query: + description: A top-level property of the first data + input, to use for query parameters + type: string + replytx: + description: A top-level property of the first data + input, to use to dynamically set whether to pin the + response (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set + on the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply + message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set + on the reply message' + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be + relative if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates a new subscription for an application to receive events + from FireFly + operationId: postNewSubscriptionNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an event + is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription will + only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: Whether your appplication 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the webhook + request' + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. Only + applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set on + the webhook request' + type: string + description: 'Webhooks only: Static query params to set on the + webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send a + reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + type: object + responses: + "201": + content: + application/json: + schema: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: Whether your appplication 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set on + the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + put: + description: Update an existing subscription + operationId: putSubscriptionNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an event + is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription will + only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: Whether your appplication 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the webhook + request' + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. Only + applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set on + the webhook request' + type: string + description: 'Webhooks only: Static query params to set on the + webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send a + reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: Whether your appplication 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set on + the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/subscriptions/{subid}: + delete: + description: Deletes a subscription + operationId: deleteSubscriptionNamespace + parameters: + - description: The subscription ID + in: path + name: subid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Non-Default Namespace + get: + description: Gets a subscription by its ID + operationId: getSubscriptionByIDNamespace + parameters: + - description: The subscription ID + in: path + name: subid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When set, the API will return additional status information if + available + in: query + name: fetchstatus + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: Whether your appplication 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set on + the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/accounts: + get: + description: Gets a list of token accounts + operationId: getTokenAccountsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + key: + description: The blockchain signing identity this balance applies + to + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/accounts/{key}/pools: + get: + description: Gets a list of token pools that contain a given token account key + operationId: getTokenAccountPoolsNamespace + parameters: + - description: The key for the token account. The exact format may vary based + on the token connector use + in: path + name: key + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + pool: + description: The UUID the token pool this balance entry applies + to + format: uuid + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/approvals: + get: + description: Gets a list of token approvals + operationId: getTokenApprovalsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: active + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: approved + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainevent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: localid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messagehash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: operator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: protocolid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: subject + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + active: + description: Indicates if this approval is currently active + (only one approval can be active per subject) + type: boolean + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes + permission (false) + type: boolean + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the token approval + format: date-time + type: string + info: + additionalProperties: + description: 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 + description: 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 + type: object + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token approval, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated + with this approval using the data field of the approval in + a compatible token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated + with this approval using the data field of the approval in + a compatible token connector + format: byte + type: string + namespace: + description: The namespace for the approval, which must match + the namespace of the token pool + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + subject: + description: A string identifying the parties and entities in + the scope of this approval, as provided by the token connector + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in + use supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates a token approval + operationId: postTokenApprovalNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes permission + (false) + type: boolean + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the approval. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the approval. See your chosen token connector documentation + for details + type: object + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + message: + description: The UUID of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: uuid + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The name or UUID of a token pool. Required if more + than one pool exists. + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + active: + description: Indicates if this approval is currently active (only + one approval can be active per subject) + type: boolean + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes permission + (false) + type: boolean + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the token approval + format: date-time + type: string + info: + additionalProperties: + description: 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 + description: 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 + type: object + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token approval, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the approval, which must match + the namespace of the token pool + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + subject: + description: A string identifying the parties and entities in + the scope of this approval, as provided by the token connector + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + active: + description: Indicates if this approval is currently active (only + one approval can be active per subject) + type: boolean + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes permission + (false) + type: boolean + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the token approval + format: date-time + type: string + info: + additionalProperties: + description: 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 + description: 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 + type: object + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token approval, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the approval, which must match + the namespace of the token pool + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + subject: + description: A string identifying the parties and entities in + the scope of this approval, as provided by the token connector + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/balances: + get: + description: Gets a list of token balances + operationId: getTokenBalancesNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: balance + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tokenindex + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: uri + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + balance: + description: The numeric balance. For non-fungible tokens will + always be 1. For fungible tokens, the number of decimals for + the token pool should be considered when interpreting the + balance. For example, with 18 decimals a fractional balance + of 10.234 will be returned as 10,234,000,000,000,000,000 + type: string + connector: + description: The token connector that is responsible for the + token pool of this balance entry + type: string + key: + description: The blockchain signing identity this balance applies + to + type: string + namespace: + description: The namespace of the token pool for this balance + entry + type: string + pool: + description: The UUID the token pool this balance entry applies + to + format: uuid + type: string + tokenIndex: + description: The index of the token within the pool that this + balance applies to + type: string + updated: + description: The last time the balance was updated by applying + a transfer event + format: date-time + type: string + uri: + description: The URI of the token this balance entry applies + to + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/burn: + post: + description: Burns some tokens + operationId: postTokenBurnNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + type: object + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this transfer + applies to + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/connectors: + get: + description: Gets the list of token connectors currently in use + operationId: getTokenConnectorsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + name: + description: The name of the token connector, as configured + in the FireFly core configuration file + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/mint: + post: + description: Mints some tokens + operationId: postTokenMintNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + type: object + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this transfer + applies to + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/pools: + get: + description: Gets a list of token pools + operationId: getTokenPoolsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: decimals + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: locator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: standard + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: symbol + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for + details + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + type: object + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network to index this pool + format: uuid + type: string + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + standard: + description: The ERC standard the token pool conforms to, as + reported by the token connector + type: string + state: + description: The current state of the token pool + enum: + - unknown + - pending + - confirmed + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Creates a new token pool + operationId: postTokenPoolNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + config: + additionalProperties: + description: 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 + description: 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 + type: object + connector: + description: 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 + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: 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 + type: string + name: + description: The name of the token pool. Note the name is not validated + against the description of the token on the blockchain + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network to index this pool + format: uuid + type: string + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + state: + description: The current state of the token pool + enum: + - unknown + - pending + - confirmed + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network to index this pool + format: uuid + type: string + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + state: + description: The current state of the token pool + enum: + - unknown + - pending + - confirmed + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/pools/{nameOrId}: + get: + description: Gets a token pool by its name or its ID + operationId: getTokenPoolByNameOrIDNamespace + parameters: + - description: The token pool name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network to index this pool + format: uuid + type: string + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + state: + description: The current state of the token pool + enum: + - unknown + - pending + - confirmed + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/transfers: + get: + description: Gets a list of token transfers + operationId: getTokenTransfersNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: The sending or receiving token account for a token transfer + in: query + name: fromOrTo + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: amount + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainevent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: from + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: localid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messagehash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: protocolid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: to + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tokenindex + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: uri + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On + input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated + with this transfer using the data field of the transfer in + a compatible token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated + with this transfer using the data field of the transfer in + a compatible token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in + use supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + post: + description: Transfers some tokens + operationId: postTokenTransferNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + type: object + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this transfer + applies to + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/tokens/transfers/{transferId}: + get: + description: Gets a token transfer by its ID + operationId: getTokenTransferByIDNamespace + parameters: + - description: The token transfer ID + in: path + name: transferId + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/transactions: + get: + description: Gets a list of transactions + operationId: getTxnsNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainids + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + blockchainIds: + description: 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 + items: + description: 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 + type: string + type: array + created: + description: 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 + format: date-time + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + idempotencyKey: + description: An optional unique identifier for a transaction. + Cannot be duplicated within a namespace, thus allowing idempotent + submission of transactions to the API + type: string + namespace: + description: The namespace of the FireFly transaction + type: string + type: + description: The type of the FireFly transaction + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/transactions/{txnid}: + get: + description: Gets a transaction by its ID + operationId: getTxnByIDNamespace + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainids + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + properties: + blockchainIds: + description: 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 + items: + description: 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 + type: string + type: array + created: + description: 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 + format: date-time + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + idempotencyKey: + description: An optional unique identifier for a transaction. + Cannot be duplicated within a namespace, thus allowing idempotent + submission of transactions to the API + type: string + namespace: + description: The namespace of the FireFly transaction + type: string + type: + description: The type of the FireFly transaction + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/transactions/{txnid}/blockchainevents: + get: + description: Gets a list blockchain events for a specific transaction + operationId: getTxnBlockchainEventsNamespace + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + id: + description: The UUID assigned to the event by FireFly + format: uuid + type: string + info: + additionalProperties: + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + type: object + listener: + description: The UUID of the listener that detected this event, + or nil for built-in events in the system namespace + format: uuid + type: string + name: + description: The name of the event in the blockchain smart contract + type: string + namespace: + description: The namespace of the listener that detected this + blockchain event + type: string + output: + additionalProperties: + description: The data output by the event, parsed to JSON + according to the interface of the smart contract + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + type: object + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely on the blockchain (convention for plugins + is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) + type: string + source: + description: The blockchain plugin or token service that detected + the event + type: string + timestamp: + description: The time allocated to this event by the blockchain. + This is the block timestamp for most blockchain connectors + format: date-time + type: string + tx: + description: 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 + properties: + blockchainId: + description: The blockchain transaction ID, in the format + specific to the blockchain involved in the transaction. + Not all FireFly transactions include a blockchain + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/transactions/{txnid}/operations: + get: + description: Gets a list of operations in a specific transaction + operationId: getTxnOpsNamespace + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for + this operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a + previous operation, this field points to the UUID of the operation + being retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/transactions/{txnid}/status: + get: + description: Gets the status of a transaction + operationId: getTxnStatusNamespace + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + details: + description: A set of records describing the activities within + the transaction known by the local FireFly node + items: + description: A set of records describing the activities within + the transaction known by the local FireFly node + properties: + error: + description: If an error occurred related to the detail + entry, it is included here + type: string + id: + description: The UUID of the entry referenced by this detail. + The type of this record can be inferred from the entry + type + format: uuid + type: string + info: + additionalProperties: + description: Output details for this entry + description: Output details for this entry + type: object + status: + description: The status of the detail record. Cases where + an event is required for completion, but has not arrived + yet are marked with a 'pending' record + type: string + subtype: + description: A sub-type, such as an operation type, or an + event type + type: string + timestamp: + description: The time relevant to when the record was updated, + such as the time an event was created, or the last update + time of an operation + format: date-time + type: string + type: + description: The type of the transaction status detail record + type: string + type: object + type: array + status: + description: The overall computed status of the transaction, after + analyzing the details during the API call + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/verifiers: + get: + description: Gets a list of verifiers + operationId: getVerifiersNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: identity + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: value + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time this verifier was created on this node + format: date-time + type: string + hash: + description: Hash used as a globally consistent identifier for + this namespace + type + value combination on every node in + the network + format: byte + type: string + identity: + description: The UUID of the parent identity that has claimed + this verifier + format: uuid + type: string + namespace: + description: The namespace of the verifier + type: string + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/verifiers/{hash}: + get: + description: Gets a verifier by its hash + operationId: getVerifierByIDNamespace + parameters: + - description: The hash of the verifier + in: path + name: hash + required: true + schema: + example: hash + type: string + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time this verifier was created on this node + format: date-time + type: string + hash: + description: Hash used as a globally consistent identifier for + this namespace + type + value combination on every node in the + network + format: byte + type: string + identity: + description: The UUID of the parent identity that has claimed + this verifier + format: uuid + type: string + namespace: + description: The namespace of the verifier + type: string + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /namespaces/{ns}/verifiers/resolve: + post: + description: Resolves an input key to a signing key + operationId: postVerifiersResolveNamespace + parameters: + - description: The namespace which scopes this request + in: path + name: ns + required: true + schema: + example: default + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, or + Fabric MSP identifier + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + description: Success + default: + description: "" + tags: + - Non-Default Namespace + /network/action: + post: + description: Notify all nodes in the network of a new governance action + operationId: postNetworkAction + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + type: + description: The action to be performed + enum: + - terminate + type: string + type: object + responses: + "202": + content: + application/json: + schema: + properties: + type: + description: The action to be performed + enum: + - terminate + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/diddocs/{did}: + get: + description: Gets a DID document by its DID + operationId: getNetworkDIDDocByDID + parameters: + - description: The identity DID + in: path + name: did + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + '@context': + description: See https://www.w3.org/TR/did-core/#json-ld + items: + description: See https://www.w3.org/TR/did-core/#json-ld + type: string + type: array + authentication: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + type: array + id: + description: See https://www.w3.org/TR/did-core/#did-document-properties + type: string + verificationMethod: + description: See https://www.w3.org/TR/did-core/#did-document-properties + items: + description: See https://www.w3.org/TR/did-core/#did-document-properties + properties: + blockchainAcountId: + description: For blockchains like Ethereum that represent + signing identities directly by their public key summarized + in an account string + type: string + controller: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + dataExchangePeerID: + description: A string provided by your Data Exchange plugin, + that it uses a technology specific mechanism to validate + against when messages arrive from this identity + type: string + id: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + mspIdentityString: + description: For Hyperledger Fabric where the signing identity + is represented by an MSP identifier (containing X509 certificate + DN strings) that were validated by your local MSP + type: string + type: + description: See https://www.w3.org/TR/did-core/#service-properties + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/identities: + get: + deprecated: true + description: Gets the list of identities in the network (deprecated - use /identities + instead of /network/identities + operationId: getNetworkIdentities + parameters: + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to + prove data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum + address, or Fabric MSP identifier + type: string + type: object + type: array + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /network/identities/{did}: + get: + deprecated: true + description: Gets an identity by its DID + operationId: getNetworkIdentityByDID + parameters: + - description: The identity DID + in: path + name: did + required: true + schema: + type: string + - description: When set, the API will return the verifier for this identity + in: query + name: fetchverifiers + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + verifiers: + description: The verifiers, such as blockchain signing keys, that + have been bound to this identity and can be used to prove data + orignates from that identity + items: + description: The verifiers, such as blockchain signing keys, + that have been bound to this identity and can be used to prove + data orignates from that identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/nodes: + get: + description: Gets a list of nodes in the network + operationId: getNetworkNodes + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /network/nodes/{nameOrId}: + get: + description: Gets information about a specific node in the network + operationId: getNetworkNode + parameters: + - description: The name or ID of the node + in: path + name: nameOrId + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/nodes/self: + post: + description: Instructs this FireFly node to register itself on the network + operationId: postNodesSelf + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + additionalProperties: {} + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/organizations: + get: + description: Gets a list of orgs in the network + operationId: getNetworkOrgs + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: description + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: did + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.claim + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.update + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messages.verification + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: parent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: profile + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and + node identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root + organization identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Registers a new org in the network + operationId: postNewOrganization + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + key: + description: The blockchain signing key to use to make the claim + to the identity. Must be available to the local node to sign the + identity claim. Will become a verifier on the established identity + type: string + name: + description: The name of the identity. The name must be unique within + the type and namespace + type: string + parent: + description: On input the parent can be specified directly as the + UUID of and existing identity, or as a DID to resolve to that + identity, or an organization name. The parent must already have + been registered, and its blockchain signing key must be available + to the local node to sign the verification + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/organizations/{nameOrId}: + get: + description: Gets information about a specific org in the network + operationId: getNetworkOrg + parameters: + - description: The name or ID of the org + in: path + name: nameOrId + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /network/organizations/self: + post: + description: Instructs this FireFly node to register its org on the network + operationId: postNewOrganizationSelf + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + example: "true" + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + additionalProperties: {} + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + created: + description: The creation time of the identity + format: date-time + type: string + description: + description: A description of the identity. Part of the updatable + profile information of an identity + type: string + did: + description: The DID of the identity. Unique across namespaces + within a FireFly network + type: string + id: + description: The UUID of the identity + format: uuid + type: string + messages: + description: References to the broadcast messages that established + this identity and proved ownership of the associated verifiers + (keys) + properties: + claim: + description: The UUID of claim message + format: uuid + type: string + update: + description: The UUID of the most recently applied update + message. Unset if no updates have been confirmed + format: uuid + type: string + verification: + description: The UUID of claim message. Unset for root organization + identities + format: uuid + type: string + type: object + name: + description: The name of the identity. The name must be unique + within the type and namespace + type: string + namespace: + description: The namespace of the identity. Organization and node + identities are always defined in the ff_system namespace + type: string + parent: + description: The UUID of the parent identity. Unset for root organization + identities + format: uuid + type: string + profile: + additionalProperties: + description: A set of metadata for the identity. Part of the + updatable profile information of an identity + description: A set of metadata for the identity. Part of the updatable + profile information of an identity + type: object + type: + description: The type of the identity + enum: + - org + - node + - custom + type: string + updated: + description: The last update time of the identity profile + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /operations: + get: + description: Gets a a list of operations + operationId: getOps + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: error + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: input + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: output + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: plugin + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: retry + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: status + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for + this operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a + previous operation, this field points to the UUID of the operation + being retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /operations/{opid}: + get: + description: Gets an operation by ID + operationId: getOpByID + parameters: + - description: The operation ID key to get + in: path + name: opid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /operations/{opid}/retry: + post: + description: Retries a failed operation + operationId: postOpRetry + parameters: + - description: The UUID of the operation + in: path + name: opid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + additionalProperties: {} + type: object + responses: + "202": + content: + application/json: + schema: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for this + operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a previous + operation, this field points to the UUID of the operation being + retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /pins: + get: + description: Queries the list of pins received from the blockchain + operationId: getPins + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: batch + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: dispatched + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: index + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: masked + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: sequence + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + batch: + description: The UUID of the batch of messages this pin is part + of + format: uuid + type: string + batchHash: + description: The manifest hash batch of messages this pin is + part of + format: byte + type: string + created: + description: The time the FireFly node created the pin + format: date-time + type: string + dispatched: + description: Once true, this pin has been processed and will + not be processed again + type: boolean + hash: + description: The hash represents a topic within a message in + the batch. If a message has multiple topics, then multiple + pins are created. If the message is private, the hash is masked + for privacy + format: byte + type: string + index: + description: The index of this pin within the batch. One pin + is created for each topic, of each message in the batch + format: int64 + type: integer + masked: + description: True if the pin is for a private message, and hence + is masked with the group ID and salted with a nonce so observers + of the blockchain cannot use pin hash to match this transaction + to other transactions or participants + type: boolean + namespace: + description: The namespace of the pin + type: string + sequence: + description: The order of the pin in the local FireFly database, + which matches the order in which pins were delivered to FireFly + by the blockchain connector event stream + format: int64 + type: integer + signer: + description: The blockchain signing key that submitted this + transaction, as passed through to FireFly by the smart contract + that emitted the blockchain event + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /pins/rewind: + post: + description: Force a rewind of the event aggregator to a previous position, + to re-evaluate all unconfirmed pins since that point + operationId: postPinsRewind + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + batch: + description: The ID of the batch to which the event aggregator should + rewind. Either sequence or batch must be specified + format: uuid + type: string + sequence: + description: The sequence of the pin to which the event aggregator + should rewind. Either sequence or batch must be specified + format: int64 + type: integer + type: object + responses: + "200": + content: + application/json: + schema: + properties: + batch: + description: The ID of the batch to which the event aggregator + should rewind. Either sequence or batch must be specified + format: uuid + type: string + sequence: + description: The sequence of the pin to which the event aggregator + should rewind. Either sequence or batch must be specified + format: int64 + type: integer + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /status: + get: + description: Gets the status of this namespace + operationId: getStatus + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + multiparty: + description: Information about the multi-party system configured + on this namespace + properties: + contract: + description: Information about the multi-party smart contract + configured for this namespace + properties: + active: + description: The currently active FireFly smart contract + properties: + firstEvent: + description: 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 + type: string + index: + description: The index of this contract in the config + file + type: integer + info: + description: Additional info about the current status + of the multi-party contract + properties: + finalEvent: + description: The identifier for the final blockchain + event received from this contract before termination + type: string + subscription: + description: The backend identifier of the subscription + for the FireFly BatchPin contract + type: string + version: + description: The version of this multiparty contract + type: integer + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a Fabric + chaincode name and channel + type: object + terminated: + description: Previously-terminated FireFly smart contracts + items: + description: Previously-terminated FireFly smart contracts + properties: + firstEvent: + description: 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 + type: string + index: + description: The index of this contract in the config + file + type: integer + info: + description: Additional info about the current status + of the multi-party contract + properties: + finalEvent: + description: The identifier for the final blockchain + event received from this contract before termination + type: string + subscription: + description: The backend identifier of the subscription + for the FireFly BatchPin contract + type: string + version: + description: The version of this multiparty + contract + type: integer + type: object + location: + description: A blockchain specific contract identifier. + For example an Ethereum contract address, or a + Fabric chaincode name and channel + type: object + type: array + type: object + enabled: + description: Whether multi-party mode is enabled for this + namespace + type: boolean + type: object + namespace: + description: The namespace that this status applies to + properties: + created: + description: The time the namespace was created + format: date-time + type: string + description: + description: A description of the namespace + type: string + name: + description: The local namespace name + type: string + networkName: + description: The shared namespace name within the multiparty + network + type: string + type: object + node: + description: Details of the local node + properties: + id: + description: The UUID of the node, if registered + format: uuid + type: string + name: + description: The name of this node, as specified in the local + configuration + type: string + registered: + description: Whether the node has been successfully registered + type: boolean + type: object + org: + description: Details of the root organization identity registered + for this namespace on the local node + properties: + did: + description: The DID of the organization identity, if registered + type: string + id: + description: The UUID of the organization, if registered + format: uuid + type: string + name: + description: The name of the node operator organization, as + specified in the local configuration + type: string + registered: + description: Whether the organization has been successfully + registered + type: boolean + verifiers: + description: Array of verifiers (blockchain keys) owned by + this identity + items: + description: Array of verifiers (blockchain keys) owned + by this identity + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum + address, or Fabric MSP identifier + type: string + type: object + type: array + type: object + plugins: + description: Information about plugins configured on this namespace + properties: + blockchain: + description: The blockchain plugins on this namespace + items: + description: The blockchain plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + dataExchange: + description: The data exchange plugins on this namespace + items: + description: The data exchange plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + database: + description: The database plugins on this namespace + items: + description: The database plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + events: + description: The event plugins on this namespace + items: + description: The event plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + identity: + description: The identity plugins on this namespace + items: + description: The identity plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + sharedStorage: + description: The shared storage plugins on this namespace + items: + description: The shared storage plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + tokens: + description: The token plugins on this namespace + items: + description: The token plugins on this namespace + properties: + name: + description: The name of the plugin + type: string + pluginType: + description: The type of the plugin + type: string + type: object + type: array + type: object + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /status/batchmanager: + get: + description: Gets the status of the batch manager + operationId: getStatusBatchManager + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + processors: + description: An array of currently active batch processors + items: + description: An array of currently active batch processors + properties: + dispatcher: + description: The type of dispatcher for this processor + type: string + name: + description: The name of the processor, which includes details + of the attributes of message are allocated to this processor + type: string + status: + description: The flush status for this batch processor + properties: + averageBatchBytes: + description: The average byte size of each batch + format: int64 + type: integer + averageBatchData: + description: The average number of data attachments + included in each batch + format: double + type: number + averageBatchMessages: + description: The average number of messages included + in each batch + format: double + type: number + averageFlushTimeMS: + description: The average amount of time spent flushing + each batch + format: int64 + type: integer + blocked: + description: True if the batch flush is in a retry loop, + due to errors being returned by the plugins + type: boolean + flushing: + description: If a flush is in progress, this is the + UUID of the batch being flushed + format: uuid + type: string + lastFlushError: + description: The last error received by this batch processor + while flushing + type: string + lastFlushErrorTime: + description: The time of the last flush + format: date-time + type: string + lastFlushStartTime: + description: The last time a flush was performed + format: date-time + type: string + totalBatches: + description: The total count of batches flushed by this + processor since it started + format: int64 + type: integer + totalErrors: + description: The total count of error flushed encountered + by this processor since it started + format: int64 + type: integer + type: object + type: object + type: array + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /subscriptions: + get: + description: Gets a list of subscriptions + operationId: getSubscriptions + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: events + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: filters + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: options + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: transport + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' + instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event + in the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this + filter is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the + subscription + type: string + options: + description: Subscription options + properties: + fastack: + description: 'Webhooks only: When true the event will be + acknowledged before the webhook is invoked, allowing parallel + invocations' + type: boolean + firstEvent: + description: Whether your appplication 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on + the webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + input: + description: 'Webhooks only: A set of options to extract + data from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data + input, to use for the request body. Default is the + whole first body + type: string + headers: + description: A top-level property of the first data + input, to use for headers + type: string + path: + description: A top-level property of the first data + input, to use for a path to append with escaping to + the webhook path + type: string + query: + description: A top-level property of the first data + input, to use for query parameters + type: string + replytx: + description: A top-level property of the first data + input, to use to dynamically set whether to pin the + response (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set + on the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply + message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set + on the reply message' + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be + relative if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates a new subscription for an application to receive events + from FireFly + operationId: postNewSubscription + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an event + is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription will + only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: Whether your appplication 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the webhook + request' + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. Only + applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set on + the webhook request' + type: string + description: 'Webhooks only: Static query params to set on the + webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send a + reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + type: object + responses: + "201": + content: + application/json: + schema: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: Whether your appplication 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set on + the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + put: + description: Update an existing subscription + operationId: putSubscription + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an event + is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription will + only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: Whether your appplication 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the webhook + request' + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. Only + applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set on + the webhook request' + type: string + description: 'Webhooks only: Static query params to set on the + webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send a + reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: Whether your appplication 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set on + the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /subscriptions/{subid}: + delete: + description: Deletes a subscription + operationId: deleteSubscription + parameters: + - description: The subscription ID + in: path + name: subid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "204": + content: + application/json: {} + description: Success + default: + description: "" + tags: + - Default Namespace + get: + description: Gets a subscription by its ID + operationId: getSubscriptionByID + parameters: + - description: The subscription ID + in: path + name: subid + required: true + schema: + type: string + - description: When set, the API will return additional status information if + available + in: query + name: fetchstatus + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: Creation time of the subscription + format: date-time + type: string + ephemeral: + description: 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 + type: boolean + filter: + description: Server-side filter to apply to events + properties: + author: + description: 'Deprecated: Please use ''message.author'' instead' + type: string + blockchainevent: + description: Filters specific to blockchain events. If an + event is not a blockchain event, these filters are ignored + properties: + listener: + description: 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 + type: string + name: + description: Regular expression to apply to the blockchain + event 'name' field, which is the name of the event in + the underlying blockchain smart contract + type: string + type: object + events: + description: Regular expression to apply to the event type, + to subscribe to a subset of event types + type: string + group: + description: 'Deprecated: Please use ''message.group'' instead' + type: string + message: + description: Filters specific to message events. If an event + is not a message event, these filters are ignored + properties: + author: + description: Regular expression to apply to the message + 'header.author' field + type: string + group: + description: Regular expression to apply to the message + 'header.group' field + type: string + tag: + description: Regular expression to apply to the message + 'header.tag' field + type: string + type: object + tag: + description: 'Deprecated: Please use ''message.tag'' instead' + type: string + topic: + description: 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 + type: string + topics: + description: 'Deprecated: Please use ''topic'' instead' + type: string + transaction: + description: Filters specific to events with a transaction. + If an event is not associated with a transaction, this filter + is ignored + properties: + type: + description: Regular expression to apply to the transaction + 'type' field + type: string + type: object + type: object + id: + description: The UUID of the subscription + format: uuid + type: string + name: + description: 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 + type: string + namespace: + description: The namespace of the subscription. A subscription + will only receive events generated in the namespace of the subscription + type: string + options: + description: Subscription options + properties: + fastack: + description: 'Webhooks only: When true the event will be acknowledged + before the webhook is invoked, allowing parallel invocations' + type: boolean + firstEvent: + description: Whether your appplication 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' + type: string + headers: + additionalProperties: + description: 'Webhooks only: Static headers to set on the + webhook request' + type: string + description: 'Webhooks only: Static headers to set on the + webhook request' + type: object + input: + description: 'Webhooks only: A set of options to extract data + from the first JSON input data in the incoming message. + Only applies if withData=true' + properties: + body: + description: A top-level property of the first data input, + to use for the request body. Default is the whole first + body + type: string + headers: + description: A top-level property of the first data input, + to use for headers + type: string + path: + description: A top-level property of the first data input, + to use for a path to append with escaping to the webhook + path + type: string + query: + description: A top-level property of the first data input, + to use for query parameters + type: string + replytx: + description: A top-level property of the first data input, + to use to dynamically set whether to pin the response + (so the requester can choose) + type: string + type: object + json: + description: 'Webhooks only: Whether to assume the response + body is JSON, regardless of the returned Content-Type' + type: boolean + method: + description: 'Webhooks only: HTTP method to invoke. Default=POST' + type: string + query: + additionalProperties: + description: 'Webhooks only: Static query params to set + on the webhook request' + type: string + description: 'Webhooks only: Static query params to set on + the webhook request' + type: object + readAhead: + description: 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 + maximum: 65535 + minimum: 0 + type: integer + reply: + description: 'Webhooks only: Whether to automatically send + a reply event, using the body returned by the webhook' + type: boolean + replytag: + description: 'Webhooks only: The tag to set on the reply message' + type: string + replytx: + description: 'Webhooks only: The transaction type to set on + the reply message' + type: string + url: + description: 'Webhooks only: HTTP url to invoke. Can be relative + if a base URL is set in the webhook plugin config' + type: string + withData: + description: 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. + type: boolean + type: object + transport: + description: The transport plugin responsible for event delivery + (WebSockets, Webhooks, JMS, NATS etc.) + type: string + updated: + description: Last time the subscription was updated + format: date-time + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/accounts: + get: + description: Gets a list of token accounts + operationId: getTokenAccounts + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + key: + description: The blockchain signing identity this balance applies + to + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/accounts/{key}/pools: + get: + description: Gets a list of token pools that contain a given token account key + operationId: getTokenAccountPools + parameters: + - description: The key for the token account. The exact format may vary based + on the token connector use + in: path + name: key + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + pool: + description: The UUID the token pool this balance entry applies + to + format: uuid + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/approvals: + get: + description: Gets a list of token approvals + operationId: getTokenApprovals + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: active + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: approved + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainevent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: localid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messagehash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: operator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: protocolid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: subject + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + active: + description: Indicates if this approval is currently active + (only one approval can be active per subject) + type: boolean + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes + permission (false) + type: boolean + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the token approval + format: date-time + type: string + info: + additionalProperties: + description: 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 + description: 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 + type: object + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token approval, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated + with this approval using the data field of the approval in + a compatible token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated + with this approval using the data field of the approval in + a compatible token connector + format: byte + type: string + namespace: + description: The namespace for the approval, which must match + the namespace of the token pool + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + subject: + description: A string identifying the parties and entities in + the scope of this approval, as provided by the token connector + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in + use supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates a token approval + operationId: postTokenApproval + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes permission + (false) + type: boolean + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the approval. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the approval. See your chosen token connector documentation + for details + type: object + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + message: + description: The UUID of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: uuid + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The name or UUID of a token pool. Required if more + than one pool exists. + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + active: + description: Indicates if this approval is currently active (only + one approval can be active per subject) + type: boolean + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes permission + (false) + type: boolean + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the token approval + format: date-time + type: string + info: + additionalProperties: + description: 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 + description: 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 + type: object + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token approval, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the approval, which must match + the namespace of the token pool + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + subject: + description: A string identifying the parties and entities in + the scope of this approval, as provided by the token connector + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + active: + description: Indicates if this approval is currently active (only + one approval can be active per subject) + type: boolean + approved: + description: Whether this record grants permission for an operator + to perform actions on the token balance (true), or revokes permission + (false) + type: boolean + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the token approval + format: date-time + type: string + info: + additionalProperties: + description: 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 + description: 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 + type: object + key: + description: The blockchain signing key for the approval request. + On input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token approval, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this approval using the data field of the approval in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the approval, which must match + the namespace of the token pool + type: string + operator: + description: The blockchain identity that is granted the approval + type: string + pool: + description: The UUID the token pool this approval applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + subject: + description: A string identifying the parties and entities in + the scope of this approval, as provided by the token connector + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/balances: + get: + description: Gets a list of token balances + operationId: getTokenBalances + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: balance + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tokenindex + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: updated + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: uri + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + balance: + description: The numeric balance. For non-fungible tokens will + always be 1. For fungible tokens, the number of decimals for + the token pool should be considered when interpreting the + balance. For example, with 18 decimals a fractional balance + of 10.234 will be returned as 10,234,000,000,000,000,000 + type: string + connector: + description: The token connector that is responsible for the + token pool of this balance entry + type: string + key: + description: The blockchain signing identity this balance applies + to + type: string + namespace: + description: The namespace of the token pool for this balance + entry + type: string + pool: + description: The UUID the token pool this balance entry applies + to + format: uuid + type: string + tokenIndex: + description: The index of the token within the pool that this + balance applies to + type: string + updated: + description: The last time the balance was updated by applying + a transfer event + format: date-time + type: string + uri: + description: The URI of the token this balance entry applies + to + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/burn: + post: + description: Burns some tokens + operationId: postTokenBurn + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + type: object + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + tokenIndex: + description: The index of the token within the pool that this transfer + applies to + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/connectors: + get: + description: Gets the list of token connectors currently in use + operationId: getTokenConnectors + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + name: + description: The name of the token connector, as configured + in the FireFly core configuration file + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/mint: + post: + description: Mints some tokens + operationId: postTokenMint + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + type: object + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this transfer + applies to + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/pools: + get: + description: Gets a list of token pools + operationId: getTokenPools + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: decimals + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: locator + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: name + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: standard + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: state + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: symbol + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for + details + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + type: object + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network to index this pool + format: uuid + type: string + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + standard: + description: The ERC standard the token pool conforms to, as + reported by the token connector + type: string + state: + description: The current state of the token pool + enum: + - unknown + - pending + - confirmed + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Creates a new token pool + operationId: postTokenPool + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + config: + additionalProperties: + description: 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 + description: 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 + type: object + connector: + description: 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 + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: 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 + type: string + name: + description: The name of the token pool. Note the name is not validated + against the description of the token on the blockchain + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network to index this pool + format: uuid + type: string + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + state: + description: The current state of the token pool + enum: + - unknown + - pending + - confirmed + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network to index this pool + format: uuid + type: string + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + state: + description: The current state of the token pool + enum: + - unknown + - pending + - confirmed + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/pools/{nameOrId}: + get: + description: Gets a token pool by its name or its ID + operationId: getTokenPoolByNameOrID + parameters: + - description: The token pool name or ID + in: path + name: nameOrId + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + connector: + description: 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 + type: string + created: + description: The creation time of the pool + format: date-time + type: string + decimals: + description: Number of decimal places that this token has + type: integer + id: + description: The UUID of the token pool + format: uuid + type: string + info: + additionalProperties: + description: Token connector specific information about the + pool. See your chosen token connector documentation for details + description: Token connector specific information about the pool. + See your chosen token connector documentation for details + type: object + key: + description: 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 + type: string + locator: + description: A unique identifier for the pool, as provided by + the token connector + type: string + message: + description: The UUID of the broadcast message used to inform + the network to index this pool + format: uuid + type: string + name: + description: The name of the token pool. Note the name is not + validated against the description of the token on the blockchain + type: string + namespace: + description: The namespace for the token pool + type: string + standard: + description: The ERC standard the token pool conforms to, as reported + by the token connector + type: string + state: + description: The current state of the token pool + enum: + - unknown + - pending + - confirmed + type: string + symbol: + description: The token symbol. If supplied on input for an existing + on-chain token, this must match the on-chain information + type: string + tx: + description: Reference to the FireFly transaction used to create + and broadcast this pool to the network + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of token the pool contains, such as fungible/non-fungible + enum: + - fungible + - nonfungible + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/transfers: + get: + description: Gets a list of token transfers + operationId: getTokenTransfers + parameters: + - description: The sending or receiving token account for a token transfer + in: query + name: fromOrTo + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: amount + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainevent + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: connector + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: from + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: key + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: localid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: message + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: messagehash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: pool + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: protocolid + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: to + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tokenindex + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: tx.type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: uri + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On + input defaults to the first signing key of the organization + that operates the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated + with this transfer using the data field of the transfer in + a compatible token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated + with this transfer using the data field of the transfer in + a compatible token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in + use supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + post: + description: Transfers some tokens + operationId: postTokenTransfer + parameters: + - description: When true the HTTP request blocks until the message is confirmed + in: query + name: confirm + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + config: + additionalProperties: + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + description: Input only field, with token connector specific configuration + of the transfer. See your chosen token connector documentation + for details + type: object + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + idempotencyKey: + description: An optional identifier to allow idempotent submission + of requests. Stored on the transaction uniquely within a namespace + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this transfer + applies to + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + "202": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /tokens/transfers/{transferId}: + get: + description: Gets a token transfer by its ID + operationId: getTokenTransferByID + parameters: + - description: The token transfer ID + in: path + name: transferId + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + amount: + description: 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 + type: string + blockchainEvent: + description: The UUID of the blockchain event + format: uuid + type: string + connector: + description: 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 + type: string + created: + description: The creation time of the transfer + format: date-time + type: string + from: + description: The source account for the transfer. On input defaults + to the value of 'key' + type: string + key: + description: The blockchain signing key for the transfer. On input + defaults to the first signing key of the organization that operates + the node + type: string + localId: + description: The UUID of this token transfer, in the local FireFly + node + format: uuid + type: string + message: + description: The UUID of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: uuid + type: string + messageHash: + description: The hash of a message that has been correlated with + this transfer using the data field of the transfer in a compatible + token connector + format: byte + type: string + namespace: + description: The namespace for the transfer, which must match + the namespace of the token pool + type: string + pool: + description: The UUID the token pool this transfer applies to + format: uuid + type: string + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely with respect to the blockchain + type: string + to: + description: The target account for the transfer. On input defaults + to the value of 'key' + type: string + tokenIndex: + description: The index of the token within the pool that this + transfer applies to + type: string + tx: + description: If submitted via FireFly, this will reference the + UUID of the FireFly transaction (if the token connector in use + supports attaching data) + properties: + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: + description: The type of transfer such as mint/burn/transfer + enum: + - mint + - burn + - transfer + type: string + uri: + description: The URI of the token this transfer applies to + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /transactions: + get: + description: Gets a list of transactions + operationId: getTxns + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainids + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + blockchainIds: + description: 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 + items: + description: 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 + type: string + type: array + created: + description: 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 + format: date-time + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + idempotencyKey: + description: An optional unique identifier for a transaction. + Cannot be duplicated within a namespace, thus allowing idempotent + submission of transactions to the API + type: string + namespace: + description: The namespace of the FireFly transaction + type: string + type: + description: The type of the FireFly transaction + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /transactions/{txnid}: + get: + description: Gets a transaction by its ID + operationId: getTxnByID + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: blockchainids + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: id + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: idempotencykey + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + properties: + blockchainIds: + description: 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 + items: + description: 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 + type: string + type: array + created: + description: 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 + format: date-time + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + idempotencyKey: + description: An optional unique identifier for a transaction. + Cannot be duplicated within a namespace, thus allowing idempotent + submission of transactions to the API + type: string + namespace: + description: The namespace of the FireFly transaction + type: string + type: + description: The type of the FireFly transaction + enum: + - none + - unpinned + - batch_pin + - network_action + - token_pool + - token_transfer + - contract_deploy + - contract_invoke + - token_approval + - data_publish + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /transactions/{txnid}/blockchainevents: + get: + description: Gets a list blockchain events for a specific transaction + operationId: getTxnBlockchainEvents + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + id: + description: The UUID assigned to the event by FireFly + format: uuid + type: string + info: + additionalProperties: + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + description: Detailed blockchain specific information about + the event, as generated by the blockchain connector + type: object + listener: + description: The UUID of the listener that detected this event, + or nil for built-in events in the system namespace + format: uuid + type: string + name: + description: The name of the event in the blockchain smart contract + type: string + namespace: + description: The namespace of the listener that detected this + blockchain event + type: string + output: + additionalProperties: + description: The data output by the event, parsed to JSON + according to the interface of the smart contract + description: The data output by the event, parsed to JSON according + to the interface of the smart contract + type: object + protocolId: + description: An alphanumerically sortable string that represents + this event uniquely on the blockchain (convention for plugins + is zero-padded values BLOCKNUMBER/TXN_INDEX/EVENT_INDEX) + type: string + source: + description: The blockchain plugin or token service that detected + the event + type: string + timestamp: + description: The time allocated to this event by the blockchain. + This is the block timestamp for most blockchain connectors + format: date-time + type: string + tx: + description: 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 + properties: + blockchainId: + description: The blockchain transaction ID, in the format + specific to the blockchain involved in the transaction. + Not all FireFly transactions include a blockchain + type: string + id: + description: The UUID of the FireFly transaction + format: uuid + type: string + type: + description: The type of the FireFly transaction + type: string + type: object + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /transactions/{txnid}/operations: + get: + description: Gets a list of operations in a specific transaction + operationId: getTxnOps + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time the operation was created + format: date-time + type: string + error: + description: Any error reported back from the plugin for this + operation + type: string + id: + description: The UUID of the operation + format: uuid + type: string + input: + additionalProperties: + description: The input to this operation + description: The input to this operation + type: object + namespace: + description: The namespace of the operation + type: string + output: + additionalProperties: + description: Any output reported back from the plugin for + this operation + description: Any output reported back from the plugin for this + operation + type: object + plugin: + description: The plugin responsible for performing the operation + type: string + retry: + description: If this operation was initiated as a retry to a + previous operation, this field points to the UUID of the operation + being retried + format: uuid + type: string + status: + description: The current status of the operation + type: string + tx: + description: The UUID of the FireFly transaction the operation + is part of + format: uuid + type: string + type: + description: The type of the operation + enum: + - blockchain_pin_batch + - blockchain_network_action + - blockchain_deploy + - blockchain_invoke + - sharedstorage_upload_batch + - sharedstorage_upload_blob + - sharedstorage_upload_value + - sharedstorage_download_batch + - sharedstorage_download_blob + - dataexchange_send_batch + - dataexchange_send_blob + - token_create_pool + - token_activate_pool + - token_transfer + - token_approval + type: string + updated: + description: The last update time of the operation + format: date-time + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /transactions/{txnid}/status: + get: + description: Gets the status of a transaction + operationId: getTxnStatus + parameters: + - description: The transaction ID + in: path + name: txnid + required: true + schema: + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + details: + description: A set of records describing the activities within + the transaction known by the local FireFly node + items: + description: A set of records describing the activities within + the transaction known by the local FireFly node + properties: + error: + description: If an error occurred related to the detail + entry, it is included here + type: string + id: + description: The UUID of the entry referenced by this detail. + The type of this record can be inferred from the entry + type + format: uuid + type: string + info: + additionalProperties: + description: Output details for this entry + description: Output details for this entry + type: object + status: + description: The status of the detail record. Cases where + an event is required for completion, but has not arrived + yet are marked with a 'pending' record + type: string + subtype: + description: A sub-type, such as an operation type, or an + event type + type: string + timestamp: + description: The time relevant to when the record was updated, + such as the time an event was created, or the last update + time of an operation + format: date-time + type: string + type: + description: The type of the transaction status detail record + type: string + type: object + type: array + status: + description: The overall computed status of the transaction, after + analyzing the details during the API call + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /verifiers: + get: + description: Gets a list of verifiers + operationId: getVerifiers + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: created + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: hash + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: identity + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: type + schema: + type: string + - description: 'Data filter field. Prefixes supported: > >= < <= @ ^ ! !@ !^' + in: query + name: value + schema: + type: string + - description: Sort field. For multi-field sort use comma separated values (or + multiple query values) with '-' prefix for descending + in: query + name: sort + schema: + type: string + - description: Ascending sort order (overrides all fields in a multi-field sort) + in: query + name: ascending + schema: + type: string + - description: Descending sort order (overrides all fields in a multi-field + sort) + in: query + name: descending + schema: + type: string + - description: 'The number of records to skip (max: 1,000). Unsuitable for bulk + operations' + in: query + name: skip + schema: + type: string + - description: 'The maximum number of records to return (max: 1,000)' + in: query + name: limit + schema: + example: "25" + type: string + - description: Return a total count as well as items (adds extra database processing) + in: query + name: count + schema: + type: string + responses: + "200": + content: + application/json: + schema: + items: + properties: + created: + description: The time this verifier was created on this node + format: date-time + type: string + hash: + description: Hash used as a globally consistent identifier for + this namespace + type + value combination on every node in + the network + format: byte + type: string + identity: + description: The UUID of the parent identity that has claimed + this verifier + format: uuid + type: string + namespace: + description: The namespace of the verifier + type: string + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + type: array + description: Success + default: + description: "" + tags: + - Default Namespace + /verifiers/{hash}: + get: + description: Gets a verifier by its hash + operationId: getVerifierByID + parameters: + - description: The hash of the verifier + in: path + name: hash + required: true + schema: + example: hash + type: string + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + created: + description: The time this verifier was created on this node + format: date-time + type: string + hash: + description: Hash used as a globally consistent identifier for + this namespace + type + value combination on every node in the + network + format: byte + type: string + identity: + description: The UUID of the parent identity that has claimed + this verifier + format: uuid + type: string + namespace: + description: The namespace of the verifier + type: string + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /verifiers/resolve: + post: + description: Resolves an input key to a signing key + operationId: postVerifiersResolve + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + requestBody: + content: + application/json: + schema: + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, or + Fabric MSP identifier + type: string + type: object + responses: + "200": + content: + application/json: + schema: + properties: + type: + description: The type of the verifier + enum: + - ethereum_address + - fabric_msp_id + - dx_peer_id + type: string + value: + description: The verifier string, such as an Ethereum address, + or Fabric MSP identifier + type: string + type: object + description: Success + default: + description: "" + tags: + - Default Namespace + /websockets: + get: + description: Gets a list of the current WebSocket connections to this node + operationId: getWebSockets + parameters: + - description: Server-side request timeout (milliseconds, or set a custom suffix + like 10s) + in: header + name: Request-Timeout + schema: + default: 2m0s + type: string + responses: + "200": + content: + application/json: + schema: + properties: + connections: + description: List of currently active websocket client connections + items: + description: List of currently active websocket client connections + properties: + id: + description: The unique ID assigned to this client connection + type: string + remoteAddress: + description: The remote address of the connected client + (if available) + type: string + subscriptions: + description: List of subscriptions currently started by + this client + items: + description: List of subscriptions currently started by + this client + properties: + ephemeral: + description: Indicates whether the subscription is + ephemeral (vs durable) + type: boolean + name: + description: The subscription name (for durable subscriptions + only) + type: string + namespace: + description: The subscription namespace + type: string + type: object + type: array + userAgent: + description: The user agent of the connected client (if + available) + type: string + type: object + type: array + enabled: + description: Indicates whether the websockets plugin is enabled + type: boolean + type: object + description: Success + default: + description: "" + tags: + - Global +servers: +- url: http://localhost:5000 diff --git a/v1.3.1/tutorials/basic_auth/index.html b/v1.3.1/tutorials/basic_auth/index.html new file mode 100644 index 000000000..e55c53f57 --- /dev/null +++ b/v1.3.1/tutorials/basic_auth/index.html @@ -0,0 +1,3800 @@ + + + + + + + + + + + + + + + + + + + + + + + Basic Auth - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Basic Auth

+ +

Quick reference

+

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:

+
    +
  1. The main API
    2. +
  2. The SPI (for internal or admin use)
    3. +
  3. The metrics API.
    4. +
+

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.

+

FireFly has a basic auth plugin built in, which we will be configuring in this tutorial.

+
+

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.

+
+

Additional info

+ +

Create a password file

+

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 htpasswd on a command line to generate a hash file.

+

Create the test_users password hash file

+
touch test_users
+
+

Create a user named firefly

+
htpasswd -B test_users firefly
+
+

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.

+
htpasswd -B test_users <username>
+
+

Enable basic auth at the Namespace level

+

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:

+
~/.firefly/stacks/<stack_name>/runtime/config/firefly_core_0.yml
+
+

Open the config file in your favorite editor and add the auth section to the plugins list:

+
plugins:
+  auth:
+  - name: test_user_auth
+    type: basic
+    basic:
+      passwordfile: /etc/firefly/test_users
+
+

You will also need to add test_user_auth to the list of plugins used by the default namespace:

+
namespaces:
+  predefined:
+  - plugins:
+    - database0
+    - blockchain0
+    - dataexchange0
+    - sharedstorage0
+    - erc20_erc721
+    - test_user_auth
+
+

Mount the password hash file in the Docker container

+

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 docker-compose.override.yml file at:

+
~/.firefly/stacks/<stack_name>/docker-compose.override.yml
+
+

Edit the file to look like this, replacing the path to your test_users file:

+
# Add custom config overrides here
+# See https://docs.docker.com/compose/extends
+version: "2.1"
+services:
+  firefly_core_0:
+    volumes:
+      - PATH_TO_YOUR_TEST_USERS_FILE:/etc/firefly/test_users
+
+

Restart your FireFly Core container

+

To restart your FireFly stack and have Docker pick up the new volume, run:

+
ff stop <stack_name>
+ff start <stack_name>
+
+
+

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.

+
+

Test basic auth

+

After FireFly starts back up, you should be able to test that auth is working correctly by making an unauthenticated request to the API:

+
curl http://localhost:5000/api/v1/status
+{"error":"FF00169: Unauthorized"}
+
+

However, if we add the username and password that we created above, the request should still work:

+
curl -u "firefly:firefly" http://localhost:5000/api/v1/status
+{"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}}}}}
+
+

Enable auth at the HTTP listener level

+

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:

+
~/.firefly/stacks/<stack_name>/runtime/config/firefly_core_0.yml
+
+

Open the config file in your favorite editor and change the spi section to look like the following:

+
spi:
+  address: 0.0.0.0
+  enabled: true
+  port: 5101
+  publicURL: http://127.0.0.1:5101
+  auth:
+    type: basic
+    basic:
+      passwordfile: /etc/firefly/test_users
+
+

Restart FireFly to apply the changes

+
+

NOTE You will need to mount the password hash file following the instructions above if you have not already.

+
+

You can run the following to restart your stack:

+
ff stop <stack_name>
+ff start <stack_name>
+
+

Test basic auth

+

After FireFly starts back up, you should be able to query the SPI and the request should be unauthorized.

+
curl http://127.0.0.1:5101/spi/v1/namespaces
+{"error":"FF00169: Unauthorized"}
+
+

Adding the username and password that we set earlier, should make the request succeed.

+
curl -u "firefly:firefly" http://127.0.0.1:5101/spi/v1/namespaces
+[{"name":"default","networkName":"default","description":"Default predefined namespace","created":"2022-10-18T16:35:57.603205507Z"}]
+
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/broadcast_data/index.html b/v1.3.1/tutorials/broadcast_data/index.html new file mode 100644 index 000000000..fc09fce59 --- /dev/null +++ b/v1.3.1/tutorials/broadcast_data/index.html @@ -0,0 +1,3827 @@ + + + + + + + + + + + + + + + + + + + + + + + Broadcast data - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Broadcast data

+ +

Quick reference

+
    +
  • Sends a message visible to all parties in the network
    • +
  • The message describes who sent it, and exactly what data was sent
    • +
  • A message has one or more attached pieces of business data
    • +
  • Can be sent in-line, uploaded in advanced, or received from other parties
    • +
  • Can include smaller JSON payloads suitable for database storage
      +
    • These can be verified against a datatype
      • +
    +
    • +
  • Can include references to large (multi megabyte/gigabyte) Blob data
    • +
  • Sequenced via the blockchain
    • +
  • The blockchain does not contain any data, just a hash pin
    • +
  • Batched for efficiency
    • +
  • One batch can pin hundreds of message broadcasts
    • +
  • The whole batch is written to the shared storage
    • +
+

Additional info

+ +

Example 1: Inline string data

+

POST /api/v1/namespaces/default/messages/broadcast

+
{
+  "data": [
+    {
+      "value": "a string"
+    }
+  ]
+}
+
+

Example message response

+
{
+  "header": {
+    "id": "607e22ad-04fa-434a-a073-54f528ca14fb", // uniquely identifies this broadcast message
+    "type": "broadcast", // set automatically
+    "txtype": "batch_pin", // message will be batched, and sequenced via the blockchain
+    "author": "0x0a65365587a65ce44938eab5a765fe8bc6532bdf", // set automatically in this example to the node org
+    "created": "2021-07-01T18:06:24.5817016Z", // set automatically
+    "namespace": "default", // the 'default' namespace was set in the URL
+    "topics": [
+      "default" // the default topic that the message is published on, if no topic is set
+    ],
+    // datahash is calculated from the data array below
+    "datahash": "5a7bbc074441fa3231d9c8fc942d68ef9b9b646dd234bb48c57826dc723b26fd"
+  },
+  "hash": "81acf8c8f7982dbc49258535561461601cbe769752fecec0f8ce0358664979e6", // hash of the header
+  "state": "ready", // this message is stored locally but not yet confirmed
+  "data": [
+    // one item of data was stored
+    {
+      "id": "8d8635e2-7c90-4963-99cc-794c98a68b1d", // can be used to query the data in the future
+      "hash": "c95d6352f524a770a787c16509237baf7eb59967699fb9a6d825270e7ec0eacf" // sha256 hash of `"a string"`
+    }
+  ]
+}
+
+

Example 2: Inline object data to a topic (no datatype verification)

+

It is very good practice to set a tag and topic in each of your messages:

+
    +
  • tag 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.
    • +
  • topic 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.
    • +
+

POST /api/v1/namespaces/default/messages/broadcast

+
{
+  "header": {
+    "tag": "new_widget_created",
+    "topics": ["widget_id_12345"]
+  },
+  "data": [
+    {
+      "value": {
+        "id": "widget_id_12345",
+        "name": "superwidget"
+      }
+    }
+  ]
+}
+
+

Notes on why setting a topic is important

+

The FireFly aggregator uses the topic (obfuscated on chain) to determine if a +message is the next message in an in-flight sequence for any groups the node is +involved in. If it is, then that message must receive all off-chain private data +and be confirmed before any subsequent messages can be confirmed on the same sequence.

+

So if you use the same topic in every message, then a single failed send on one +topic blocks delivery of all messages between those parties, until the missing +data arrives.

+

Instead it is best practice to set the topic on your messages to a value +that identifies an ordered stream of business processing. Some examples:

+
    +
  • A long-running business process instance identifier assigned at initiation
    • +
  • A real-world business transaction identifier used off-chain
    • +
  • The agreed identifier of an asset you are attaching a stream of evidence to
    • +
  • An NFT identifier that is assigned to an asset (digital twin scenarios)
    • +
  • An agreed primary key for a data resource being reconciled between multiple parties
    • +
+

The topic field is an array, because there are cases (such as merging two identifiers) +where you need a message to be deterministically ordered across multiple sequences. +However, this is an advanced use case and you are likely to set a single topic +on the vast majority of your messages.

+

Example 3: Upload a blob with metadata and broadcast

+

Here we make two API calls.

+
    +
  1. +

    Create the data object explicitly, using a multi-part form upload

    +
    2. +
  2. +

    You can also just post JSON to this endpoint

    +
    3. +
  3. +

    Broadcast a message referring to that data

    +
    4. +
  4. +

    The Blob attachment gets published to shared storage

    +
    5. +
  5. This happens the first time a broadcast happens on a data attachment
    6. +
  6. A pin goes to the blockchain
    7. +
  7. The metadata goes into a batch with the message
    8. +
+

Multipart form post of a file

+

Example curl command (Linux/Mac) to grab an image from the internet, +and pipe it into a multi-part form post to FireFly.

+
+

Note we use autometa to cause FireFly to automatically add +the filename, and size, to the JSON part of the data object for us.

+
+
curl -sLo - https://github.com/hyperledger/firefly/raw/main/docs/firefly_logo.png \
+ | curl --form autometa=true --form file=@- \
+   http://localhost:5000/api/v1/namespaces/default/data
+
+

Example data response from Blob upload

+

Status: 200 OK - your data is uploaded to your local FireFly node

+

At this point the data has not be shared with anyone else in the network

+
{
+  // A uniquely generated ID, we can refer to when sending this data to other parties
+  "id": "97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8",
+  "validator": "json", // the "value" part is JSON
+  "namespace": "default", // from the URL
+  // The hash is a combination of the hash of the "value" metadata, and the
+  // hash of the blob
+  "hash": "997af6a9a19f06cc8a46872617b8bf974b106f744b2e407e94cc6959aa8cf0b8",
+  "created": "2021-07-01T20:20:35.5462306Z",
+  "value": {
+    "filename": "-", // dash is how curl represents the filename for stdin
+    "size": 31185 // the size of the blob data
+  },
+  "blob": {
+    // A hash reference to the blob
+    "hash": "86e6b39b04b605dd1b03f70932976775962509d29ae1ad2628e684faabe48136"
+    // Note at this point there is no public reference. The only place
+    // this data has been uploaded to is our own private data exchange.
+    // It's ready to be published to everyone (broadcast), or privately
+    // transferred (send) to other parties in the network. But that hasn't
+    // happened yet.
+  }
+}
+
+

Broadcast the uploaded data

+

Just include a reference to the id returned from the upload.

+

POST /api/v1/namespaces/default/messages/broadcast

+
{
+  "data": [
+    {
+      "id": "97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8"
+    }
+  ]
+}
+
+

Broadcasting Messages using the Sandbox

+

All of the functionality discussed above can be done through the FireFly Sandbox.

+

To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack.

+

In the sandbox, enter your message into the message field as seen in the screenshot below.

+

Initial Broadcast Message

+

Notice how the data field in the center panel updates in real time.

+

Click the blue Run button. This should return a 202 response immediately in the Server Response section and will populate the right hand panel with transaction information after a few seconds.

+

Broadcast Result

+

Go back to the FireFly UI (the URL for this would have been shown in the terminal when you started the stack) and you'll see your successful blockchain transaction

+

Successful Broadcast Transaction

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/chains/arbitrum/index.html b/v1.3.1/tutorials/chains/arbitrum/index.html new file mode 100644 index 000000000..faf8b42d2 --- /dev/null +++ b/v1.3.1/tutorials/chains/arbitrum/index.html @@ -0,0 +1,3638 @@ + + + + + + + + + + + + + + + + + + + + + + + Arbitrum - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Arbitrum

+ +

Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the Arbitrum Nitro Goerli Rollup Testnet.

+

Previous steps: Install the FireFly CLI

+

If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to Install the FireFly CLI.

+

← ① Install the FireFly CLI

+

Create an evmconnect.yml config file

+

In order to connect to the Binance Smart Chain testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called evmconnect.yml with the following contents:

+
confirmations:
+  required: 4 # choose the number of confirmations you require
+policyengine.simple:
+  fixedGasPrice: null
+  gasOracle:
+    mode: connector
+
+

For more info about confirmations, see Public vs. Permissioned

+

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

+

Creating a new stack

+

To create a local FireFly development stack and connect it to the Arbitrum testnet, we will use command line flags to customize the following settings:

+
    +
  • Create a new Ethereum based stack named arbitrum with 1 member
    • +
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
    • +
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
    • +
  • See the Arbitrum docs and select an HTTPS RPC endpoint.
    • +
  • Set the chain ID to 421613 (the correct ID for the Binance Smart Chain testnet)
    • +
  • Merge the custom config created above with the generated evmconnect config file
    • +
+

To do this, run the following command:

+
ff init ethereum arbitrum 1 \
+    --multiparty=false \
+    -n remote-rpc \
+    --remote-node-url <selected RPC endpoint> \
+    --chain-id 421613 \
+    --connector-config ~/Desktop/evmconnect.yml
+
+

Start the stack

+

Now you should be able to start your stack by running:

+
ff start arbitrum
+
+

After some time it should print out the following:

+
Web UI for member '0': http://127.0.0.1:5000/ui
+Sandbox UI for member '0': http://127.0.0.1:5109
+
+
+To see logs for your stack run:
+
+ff logs arbitrum
+
+

Get some Aribitrum

+

At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas.

+

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

+
ff accounts list arbitrum
+[
+  {
+    "address": "0x225764d1be1f137be23ddfc426b819512b5d0f3e",
+    "privateKey": "..."
+  }
+]
+
+

Copy the address listed in the output from this command. Next, check out this article https://medium.com/offchainlabs/new-g%C3%B6rli-testnet-and-getting-rinkeby-ready-for-nitro-3ff590448053 and follow the instructions to send a tweet to the developers. Make sure to change the address to the one in the CLI.

+

Arbitrum Faucet

+

Confirm the transaction on Bscscan

+

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.

+

Blockscout Scan

+

Use the public testnet

+

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.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/chains/avalanche/index.html b/v1.3.1/tutorials/chains/avalanche/index.html new file mode 100644 index 000000000..0ec6a0e9b --- /dev/null +++ b/v1.3.1/tutorials/chains/avalanche/index.html @@ -0,0 +1,3638 @@ + + + + + + + + + + + + + + + + + + + + + + + Aavalanche - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Aavalanche

+ +

Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the Avalanche C-Chain Fuji testnet.

+

Previous steps: Install the FireFly CLI

+

If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to Install the FireFly CLI.

+

← ① Install the FireFly CLI

+

Create an evmconnect.yml config file

+

In order to connect to the Avalanche testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called evmconnect.yml with the following contents:

+
confirmations:
+  required: 4 # choose the number of confirmations you require
+policyengine.simple:
+  fixedGasPrice: null
+  gasOracle:
+    mode: connector
+
+

For more info about confirmations, see Public vs. Permissioned

+

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

+

Creating a new stack

+

To create a local FireFly development stack and connect it to the Avalanche Fuji testnet, we will use command line flags to customize the following settings:

+
    +
  • Create a new Ethereum based stack named avalanche with 1 member
    • +
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
    • +
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
    • +
  • See the Avalanche docs and select and HTTPS RPC endpoint.
    • +
  • Set the chain ID to 43113 (the correct ID for the Avalanche Fuji testnet)
    • +
  • Merge the custom config created above with the generated evmconnect config file
    • +
+

To do this, run the following command:

+
ff init ethereum avalanche 1 \
+    --multiparty=false \
+    -n remote-rpc \
+    --remote-node-url <selected RPC endpoint> \
+    --chain-id 43113 \
+    --connector-config ~/Desktop/evmconnect.yml
+
+

Start the stack

+

Now you should be able to start your stack by running:

+
ff start avalanche
+
+

After some time it should print out the following:

+
Web UI for member '0': http://127.0.0.1:5000/ui
+Sandbox UI for member '0': http://127.0.0.1:5109
+
+
+To see logs for your stack run:
+
+ff logs avalanche
+
+

Get some AVAX

+

At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some AVAX, the native token for Avalanche.

+

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

+
ff accounts list avalanche
+[
+  {
+    "address": "0x6688e14f719766cc2a5856ccef63b069703d86f7",
+    "privateKey": "..."
+  }
+]
+
+

Copy the address listed in the output from this command. Go to https://faucet.avax.network/ and paste the address in the form. Make sure that the network you select is Fuji (C-Chain). Click the Request 2 AVAX button.

+

Avalanche Faucet

+

Confirm the transaction on Snowtrace

+

You should be able to go lookup your account on Snowtrace for the Fuji testnet and see that you now have a balance of 2 AVAX. Simply paste in your account address or transaction ID to search for it.

+

Snowtrace Scan

+

Use the public testnet

+

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.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/chains/binance_smart_chain/index.html b/v1.3.1/tutorials/chains/binance_smart_chain/index.html new file mode 100644 index 000000000..cb81cf75a --- /dev/null +++ b/v1.3.1/tutorials/chains/binance_smart_chain/index.html @@ -0,0 +1,3638 @@ + + + + + + + + + + + + + + + + + + + + + + + Binance Smart Chain - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Binance Smart Chain

+ +

Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the public Binance Smart Chain testnet.

+

Previous steps: Install the FireFly CLI

+

If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to Install the FireFly CLI.

+

← ① Install the FireFly CLI

+

Create an evmconnect.yml config file

+

In order to connect to the Binance Smart Chain testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called evmconnect.yml with the following contents:

+
confirmations:
+  required: 4 # choose the number of confirmations you require
+policyengine.simple:
+  fixedGasPrice: null
+  gasOracle:
+    mode: connector
+
+

For more info about confirmations, see Public vs. Permissioned

+

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

+

Creating a new stack

+

To create a local FireFly development stack and connect it to the Binance Smart Chain testnet, we will use command line flags to customize the following settings:

+
    +
  • Create a new Ethereum based stack named bsc with 1 member
    • +
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
    • +
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
    • +
  • See the Binance BscScan docs and select an HTTPS RPC endpoint.
    • +
  • Set the chain ID to 97 (the correct ID for the Binance Smart Chain testnet)
    • +
  • Merge the custom config created above with the generated evmconnect config file
    • +
+

To do this, run the following command:

+
ff init ethereum bsc 1 \
+    --multiparty=false \
+    -n remote-rpc \
+    --remote-node-url <selected RPC endpoint> \
+    --chain-id 97 \
+    --connector-config ~/Desktop/evmconnect.yml
+
+

Start the stack

+

Now you should be able to start your stack by running:

+
ff start bsc
+
+

After some time it should print out the following:

+
Web UI for member '0': http://127.0.0.1:5000/ui
+Sandbox UI for member '0': http://127.0.0.1:5109
+
+
+To see logs for your stack run:
+
+ff logs bsc
+
+

Get some BNB

+

At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some BNB, the native token for Binance Smart Chain.

+

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

+
ff accounts list bsc
+[
+  {
+    "address": "0x235461d246ab95d367925b4e91bd2755a921fdd8",
+    "privateKey": "..."
+  }
+]
+
+

Copy the address listed in the output from this command. Go to https://testnet.binance.org/faucet-smart and paste the address in the form. Go through the CAPTCH form and click the Give me BNB button.

+

BSC Faucet

+

Confirm the transaction on Bscscan

+

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.

+

BSC Scan

+

Use the public testnet

+

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.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/chains/fabric_test_network/index.html b/v1.3.1/tutorials/chains/fabric_test_network/index.html new file mode 100644 index 000000000..221b4d66a --- /dev/null +++ b/v1.3.1/tutorials/chains/fabric_test_network/index.html @@ -0,0 +1,3950 @@ + + + + + + + + + + + + + + + + + + + + + + + Fabric Test Network - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Work with Fabric-Samples Test Network

+

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

+

Previous steps: Install the FireFly CLI

+

If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to Install the FireFly CLI.

+

← ① Install the FireFly CLI

+

Start Fabric Test Network with Fabric CA

+

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 mychannel run:

+
./network.sh up createChannel -ca
+
+
+

NOTE: If you already have the Test Network running, you will need to bring it down first, by running: ./network.sh down

+
+

Deploy FireFly Chaincode

+

Next we will need to package and deploy the FireFly chaincode to mychannel 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 fabric-samples repo, you can run the following script from your test-network directory:

+
+

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.

+
+
#!/bin/bash
+
+# This file should be run from the test-network directory in the fabric-samples repo
+# It also assumes that you have the firefly repo checked out at the same level as the fabric-samples directory
+# It also assumes that the test-network is up and running and a channel named 'mychannel' has already been created
+
+cd ../../firefly/smart_contracts/fabric/firefly-go
+GO111MODULE=on go mod vendor
+cd ../../../../fabric-samples/test-network
+
+export PATH=${PWD}/../bin:$PATH
+export FABRIC_CFG_PATH=$PWD/../config/
+
+peer lifecycle chaincode package firefly.tar.gz --path ../../firefly/smart_contracts/fabric/firefly-go --lang golang --label firefly_1.0
+
+export CORE_PEER_TLS_ENABLED=true
+export CORE_PEER_LOCALMSPID="Org1MSP"
+export CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt
+export CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp
+export CORE_PEER_ADDRESS=localhost:7051
+
+peer lifecycle chaincode install firefly.tar.gz
+
+export CORE_PEER_LOCALMSPID="Org2MSP"
+export CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt
+export CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp
+export CORE_PEER_ADDRESS=localhost:9051
+
+peer lifecycle chaincode install firefly.tar.gz
+
+export CC_PACKAGE_ID=$(peer lifecycle chaincode queryinstalled --output json | jq --raw-output ".installed_chaincodes[0].package_id")
+
+peer 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"
+
+export CORE_PEER_LOCALMSPID="Org1MSP"
+export CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp
+export CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt
+export CORE_PEER_ADDRESS=localhost:7051
+
+peer 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"
+
+peer 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"
+
+

Create ccp.yml documents

+

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 ccp.yml for each organization. You will need to fill in one line by replacing the string FILL_IN_KEY_NAME_HERE, because the file name of the private key for each user is randomly generated.

+

Organization 1 connection profile

+

Create a new file at ~/org1_ccp.yml with the contents below. Replace the string FILL_IN_KEY_NAME_HERE with the filename in your fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore directory.

+
certificateAuthorities:
+  org1.example.com:
+    tlsCACerts:
+      path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp/tlscacerts/ca.crt
+    url: https://ca_org1:7054
+    grpcOptions:
+      ssl-target-name-override: org1.example.com
+    registrar:
+      enrollId: admin
+      enrollSecret: adminpw
+channels:
+  mychannel:
+    orderers:
+      - fabric_orderer
+    peers:
+      fabric_peer:
+        chaincodeQuery: true
+        endorsingPeer: true
+        eventSource: true
+        ledgerQuery: true
+client:
+  BCCSP:
+    security:
+      default:
+        provider: SW
+      enabled: true
+      hashAlgorithm: SHA2
+      level: 256
+      softVerify: true
+  credentialStore:
+    cryptoStore:
+      path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp
+    path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp
+  cryptoconfig:
+    path: /etc/firefly/organizations/peerOrganizations/org1.example.com/msp
+  logging:
+    level: info
+  organization: org1.example.com
+  tlsCerts:
+    client:
+      cert:
+        path: /etc/firefly/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/signcerts/cert.pem
+      key:
+        path: /etc/firefly/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/FILL_IN_KEY_NAME_HERE
+orderers:
+  fabric_orderer:
+    tlsCACerts:
+      path: /etc/firefly/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/tls/tlscacerts/tls-localhost-9054-ca-orderer.pem
+    url: grpcs://orderer.example.com:7050
+organizations:
+  org1.example.com:
+    certificateAuthorities:
+      - org1.example.com
+    cryptoPath: /tmp/msp
+    mspid: Org1MSP
+    peers:
+      - fabric_peer
+peers:
+  fabric_peer:
+    tlsCACerts:
+      path: /etc/firefly/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/tlscacerts/tls-localhost-7054-ca-org1.pem
+    url: grpcs://peer0.org1.example.com:7051
+version: 1.1.0%
+
+

Organization 2 connection profile

+

Create a new file at ~/org2_ccp.yml with the contents below. Replace the string FILL_IN_KEY_NAME_HERE with the filename in your fabric-samples/test-network/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/keystore directory.

+
certificateAuthorities:
+  org2.example.com:
+    tlsCACerts:
+      path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp/tlscacerts/ca.crt
+    url: https://ca_org2:8054
+    grpcOptions:
+      ssl-target-name-override: org2.example.com
+    registrar:
+      enrollId: admin
+      enrollSecret: adminpw
+channels:
+  mychannel:
+    orderers:
+      - fabric_orderer
+    peers:
+      fabric_peer:
+        chaincodeQuery: true
+        endorsingPeer: true
+        eventSource: true
+        ledgerQuery: true
+client:
+  BCCSP:
+    security:
+      default:
+        provider: SW
+      enabled: true
+      hashAlgorithm: SHA2
+      level: 256
+      softVerify: true
+  credentialStore:
+    cryptoStore:
+      path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp
+    path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp
+  cryptoconfig:
+    path: /etc/firefly/organizations/peerOrganizations/org2.example.com/msp
+  logging:
+    level: info
+  organization: org2.example.com
+  tlsCerts:
+    client:
+      cert:
+        path: /etc/firefly/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/signcerts/cert.pem
+      key:
+        path: /etc/firefly/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp/keystore/FILL_IN_KEY_NAME_HERE
+orderers:
+  fabric_orderer:
+    tlsCACerts:
+      path: /etc/firefly/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/tls/tlscacerts/tls-localhost-9054-ca-orderer.pem
+    url: grpcs://orderer.example.com:7050
+organizations:
+  org2.example.com:
+    certificateAuthorities:
+      - org2.example.com
+    cryptoPath: /tmp/msp
+    mspid: Org2MSP
+    peers:
+      - fabric_peer
+peers:
+  fabric_peer:
+    tlsCACerts:
+      path: /etc/firefly/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/tlscacerts/tls-localhost-8054-ca-org2.pem
+    url: grpcs://peer0.org2.example.com:9051
+version: 1.1.0%
+
+

Create the FireFly stack

+

Now we can create a FireFly stack and pass in these files as command line flags.

+
+

NOTE: The following command should be run in the test-network directory as it includes a relative path to the organizations directory containing each org's MSP.

+
+
ff init fabric dev \
+  --ccp "${HOME}/org1_ccp.yml" \
+  --msp "organizations" \
+  --ccp "${HOME}/org2_ccp.yml" \
+  --msp "organizations" \
+  --channel mychannel \
+  --chaincode firefly
+
+

Edit docker-compose.override.yml

+

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 ~/.firefly/stacks/dev/docker-compose.override.yml and set its contents to the following:

+
# Add custom config overrides here
+# See https://docs.docker.com/compose/extends
+version: "2.1"
+networks:
+  default:
+    name: fabric_test
+    external: true
+
+

Start FireFly stack

+

Now we can start up FireFly!

+
ff start dev
+
+

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.

+

Connecting to a remote Fabric Network

+

This same guide can be adapted to connect to a remote Fabric network running somewhere else. They key takeaways are:

+
    +
  • You need the FireFly chaincode deployed on channel in your Fabric network
    • +
  • You need to pass the channel and chaincode name when you run ff init
    • +
  • You need to provide a connection profile and the correct certs, keys, etc. for each node when you run ff init
    • +
  • Your FireFly containers will need to have network access to your Fabric network
    • +
+

Troubleshooting

+

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.

+

You may see a message something along the lines of:

+
ERROR: for firefly_core_0  Container "bc04521372aa" is unhealthy.
+Encountered errors while bringing up the project.
+
+

In this case, we need to look at the container logs to get more detail about what happened. To do this, we can run ff start 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:

+
ff start dev --verbose --no-rollback
+
+

Then we could run docker logs <container_name> to see the logs for that container.

+

No such host

+
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"}
+
+

If you see something in your logs that looks like the above, there could be a couple issues:

+
    +
  1. The hostname for one of your Fabric containers could be wrong in the ccp.yml. Check the ccp.yml for that member and make sure the hostnames are correct.
    2. +
  2. The FireFly container doesn't have networking connectivity to the Fabric containers. Check the docker-compose.override.yml file to make sure you added the fabric_test network as instructed above.
    3. +
+

No such file or directory

+
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
+
+

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 ccp.yml file for that particular member. Check your ccp.yml and make sure all the files listed there exist in your organizations directory.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/chains/images/arbitrum_faucet.png b/v1.3.1/tutorials/chains/images/arbitrum_faucet.png new file mode 100644 index 000000000..a36580943 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/arbitrum_faucet.png differ diff --git a/v1.3.1/tutorials/chains/images/arbitrum_scan.png b/v1.3.1/tutorials/chains/images/arbitrum_scan.png new file mode 100644 index 000000000..0d574db0f Binary files /dev/null and b/v1.3.1/tutorials/chains/images/arbitrum_scan.png differ diff --git a/v1.3.1/tutorials/chains/images/avalanche_faucet.png b/v1.3.1/tutorials/chains/images/avalanche_faucet.png new file mode 100644 index 000000000..39ec60062 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/avalanche_faucet.png differ diff --git a/v1.3.1/tutorials/chains/images/avalanche_snowtrace_scan.png b/v1.3.1/tutorials/chains/images/avalanche_snowtrace_scan.png new file mode 100644 index 000000000..1839a86a5 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/avalanche_snowtrace_scan.png differ diff --git a/v1.3.1/tutorials/chains/images/bsc_faucet.png b/v1.3.1/tutorials/chains/images/bsc_faucet.png new file mode 100644 index 000000000..57b577483 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/bsc_faucet.png differ diff --git a/v1.3.1/tutorials/chains/images/bsc_scan.png b/v1.3.1/tutorials/chains/images/bsc_scan.png new file mode 100644 index 000000000..608fa83e4 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/bsc_scan.png differ diff --git a/v1.3.1/tutorials/chains/images/moonbase_faucet.png b/v1.3.1/tutorials/chains/images/moonbase_faucet.png new file mode 100644 index 000000000..47b909944 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/moonbase_faucet.png differ diff --git a/v1.3.1/tutorials/chains/images/moonscan.png b/v1.3.1/tutorials/chains/images/moonscan.png new file mode 100644 index 000000000..0619fb2fd Binary files /dev/null and b/v1.3.1/tutorials/chains/images/moonscan.png differ diff --git a/v1.3.1/tutorials/chains/images/near_account.png b/v1.3.1/tutorials/chains/images/near_account.png new file mode 100644 index 000000000..fa3ee55f7 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/near_account.png differ diff --git a/v1.3.1/tutorials/chains/images/near_account_lookup.png b/v1.3.1/tutorials/chains/images/near_account_lookup.png new file mode 100644 index 000000000..eb2a41cd0 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/near_account_lookup.png differ diff --git a/v1.3.1/tutorials/chains/images/near_account_name.png b/v1.3.1/tutorials/chains/images/near_account_name.png new file mode 100644 index 000000000..f31dfc719 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/near_account_name.png differ diff --git a/v1.3.1/tutorials/chains/images/near_faucet.png b/v1.3.1/tutorials/chains/images/near_faucet.png new file mode 100644 index 000000000..44bb9136b Binary files /dev/null and b/v1.3.1/tutorials/chains/images/near_faucet.png differ diff --git a/v1.3.1/tutorials/chains/images/near_fund_account.png b/v1.3.1/tutorials/chains/images/near_fund_account.png new file mode 100644 index 000000000..cfc1b1e42 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/near_fund_account.png differ diff --git a/v1.3.1/tutorials/chains/images/near_navigate_to_wallet.png b/v1.3.1/tutorials/chains/images/near_navigate_to_wallet.png new file mode 100644 index 000000000..1d5b9ff4d Binary files /dev/null and b/v1.3.1/tutorials/chains/images/near_navigate_to_wallet.png differ diff --git a/v1.3.1/tutorials/chains/images/near_scan.png b/v1.3.1/tutorials/chains/images/near_scan.png new file mode 100644 index 000000000..a93b05598 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/near_scan.png differ diff --git a/v1.3.1/tutorials/chains/images/near_wallet_send_funds.png b/v1.3.1/tutorials/chains/images/near_wallet_send_funds.png new file mode 100644 index 000000000..b705e1dd9 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/near_wallet_send_funds.png differ diff --git a/v1.3.1/tutorials/chains/images/optimism_faucet.png b/v1.3.1/tutorials/chains/images/optimism_faucet.png new file mode 100644 index 000000000..1339d01be Binary files /dev/null and b/v1.3.1/tutorials/chains/images/optimism_faucet.png differ diff --git a/v1.3.1/tutorials/chains/images/optimism_scan.png b/v1.3.1/tutorials/chains/images/optimism_scan.png new file mode 100644 index 000000000..aeedfdb35 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/optimism_scan.png differ diff --git a/v1.3.1/tutorials/chains/images/polygon_faucet.png b/v1.3.1/tutorials/chains/images/polygon_faucet.png new file mode 100644 index 000000000..793557ea2 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/polygon_faucet.png differ diff --git a/v1.3.1/tutorials/chains/images/polygonscan_matic.png b/v1.3.1/tutorials/chains/images/polygonscan_matic.png new file mode 100644 index 000000000..9f2515e46 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/polygonscan_matic.png differ diff --git a/v1.3.1/tutorials/chains/images/tezos_explorer.png b/v1.3.1/tutorials/chains/images/tezos_explorer.png new file mode 100644 index 000000000..ec418f006 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/tezos_explorer.png differ diff --git a/v1.3.1/tutorials/chains/images/tezos_faucet.png b/v1.3.1/tutorials/chains/images/tezos_faucet.png new file mode 100644 index 000000000..99eed3315 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/tezos_faucet.png differ diff --git a/v1.3.1/tutorials/chains/images/xdc_explorer.png b/v1.3.1/tutorials/chains/images/xdc_explorer.png new file mode 100644 index 000000000..88e7ec9e2 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/xdc_explorer.png differ diff --git a/v1.3.1/tutorials/chains/images/xdc_faucet.png b/v1.3.1/tutorials/chains/images/xdc_faucet.png new file mode 100644 index 000000000..3dd3a09d3 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/xdc_faucet.png differ diff --git a/v1.3.1/tutorials/chains/images/zksync_explorer.png b/v1.3.1/tutorials/chains/images/zksync_explorer.png new file mode 100644 index 000000000..cb7ab5724 Binary files /dev/null and b/v1.3.1/tutorials/chains/images/zksync_explorer.png differ diff --git a/v1.3.1/tutorials/chains/images/zksync_faucet.png b/v1.3.1/tutorials/chains/images/zksync_faucet.png new file mode 100644 index 000000000..6a521357e Binary files /dev/null and b/v1.3.1/tutorials/chains/images/zksync_faucet.png differ diff --git a/v1.3.1/tutorials/chains/moonbeam/index.html b/v1.3.1/tutorials/chains/moonbeam/index.html new file mode 100644 index 000000000..dbf16dedd --- /dev/null +++ b/v1.3.1/tutorials/chains/moonbeam/index.html @@ -0,0 +1,3638 @@ + + + + + + + + + + + + + + + + + + + + + + + Moonbeam Testnet - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Moonbeam Testnet

+ +

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.

+

Previous steps: Install the FireFly CLI

+

If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to Install the FireFly CLI.

+

← ① Install the FireFly CLI

+

Create an evmconnect.yml config file

+

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 evmconnect.yml with the following contents:

+
confirmations:
+  required: 4 # choose the number of confirmations you require
+policyengine.simple:
+  fixedGasPrice: null
+  gasOracle:
+    mode: connector
+
+

For more info about confirmations, see Public vs. Permissioned

+

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

+

Creating a new stack

+

To create a local FireFly development stack and connect it to the Moonbeam Alpha testnet, we will use command line flags to customize the following settings:

+
    +
  • Create a new Ethereum based stack named moonbeam with 1 member
    • +
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
    • +
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
    • +
  • See the moonbeam docs and select an HTTPS RPC endpoint
    • +
  • Set the chain ID to 1287 (the correct ID for the Moonbeam Alpha testnet)
    • +
  • Merge the custom config created above with the generated evmconnect config file
    • +
+

To do this, run the following command:

+
ff init ethereum moonbeam 1 \
+    --multiparty=false \
+    -n remote-rpc \
+    --remote-node-url <selected RPC endpoint> \
+    --chain-id 1287 \
+    --connector-config ~/Desktop/evmconnect.yml
+
+

Start the stack

+

Now you should be able to start your stack by running:

+
ff start moonbeam
+
+

After some time it should print out the following:

+
Web UI for member '0': http://127.0.0.1:5000/ui
+Sandbox UI for member '0': http://127.0.0.1:5109
+
+
+To see logs for your stack run:
+
+ff logs moonbeam
+
+

Get some DEV

+

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.

+

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

+
ff accounts list moonbeam
+[
+  {
+    "address": "0x02d42c32a97c894486afbc7b717edff50c70b292",
+    "privateKey": "..."
+  }
+]
+
+

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.

+

Moonbase Alpha Faucet

+

Confirm the transaction on Moonscan

+

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.

+

Moonscan

+

Use the public testnet

+

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.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/chains/optimism/index.html b/v1.3.1/tutorials/chains/optimism/index.html new file mode 100644 index 000000000..0a79c0578 --- /dev/null +++ b/v1.3.1/tutorials/chains/optimism/index.html @@ -0,0 +1,3637 @@ + + + + + + + + + + + + + + + + + + + + + + + Optimism - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Optimism

+ +

Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the Optimism Goerli testnet.

+

Previous steps: Install the FireFly CLI

+

If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to Install the FireFly CLI.

+

← ① Install the FireFly CLI

+

Create an evmconnect.yml config file

+

In order to connect to the Optimism testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called evmconnect.yml with the following contents:

+
confirmations:
+  required: 4 # choose the number of confirmations you require
+policyengine.simple:
+  fixedGasPrice: null
+  gasOracle:
+    mode: connector
+
+

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

+

Creating a new stack

+

To create a local FireFly development stack and connect it to the Optimism testnet, we will use command line flags to customize the following settings:

+
    +
  • Create a new Ethereum based stack named optimism with 1 member
    • +
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
    • +
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
    • +
  • See the optimism docs and select an HTTPS RPC endpoint.
    • +
  • Set the chain ID to 420 (the correct ID for the Optimism testnet)
    • +
  • Merge the custom config created above with the generated evmconnect config file
    • +
+

To do this, run the following command:

+
ff init ethereum optimism 1 \
+    --multiparty=false \
+    -n remote-rpc \
+    --remote-node-url <selected RPC endpoint> \
+    --chain-id 420 \
+    --connector-config ~/Desktop/evmconnect.yml
+
+

Start the stack

+

Now you should be able to start your stack by running:

+
ff start optimism
+
+

After some time it should print out the following:

+
Web UI for member '0': http://127.0.0.1:5000/ui
+Sandbox UI for member '0': http://127.0.0.1:5109
+
+
+To see logs for your stack run:
+
+ff logs optimism
+
+

Get some Optimism

+

At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some OP, the native token for Optimism.

+

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

+
ff accounts list optimism
+[
+  {
+    "address": "0x235461d246ab95d367925b4e91bd2755a921fdd8",
+    "privateKey": "..."
+  }
+]
+
+

Copy the address listed in the output from this command. Go to https://optimismfaucet.xyz/. You will need to login to your Github account and paste the address in the form.

+

Optimism Faucet

+

Confirm the transaction on Blockcscout

+

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.

+

Blockscout Scan

+

Use the public testnet

+

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.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/chains/polygon_testnet/index.html b/v1.3.1/tutorials/chains/polygon_testnet/index.html new file mode 100644 index 000000000..b73aa62f4 --- /dev/null +++ b/v1.3.1/tutorials/chains/polygon_testnet/index.html @@ -0,0 +1,3639 @@ + + + + + + + + + + + + + + + + + + + + + + + Polygon Testnet - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Polygon Testnet

+ +

Starting with FireFly v1.1, it's easy to connect to public Ethereum chains. This guide will walk you through the steps to create a local FireFly development environment and connect it to the public Polygon Mumbai testnet.

+

Previous steps: Install the FireFly CLI

+

If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to Install the FireFly CLI.

+

← ① Install the FireFly CLI

+

Create an evmconnect.yml config file

+

In order to connect to the Polygon testnet, you will need to set a few configuration options for the evmconnect blockchain connector. Create a text file called evmconnect.yml with the following contents:

+
confirmations:
+  required: 4 # choose the number of confirmations you require
+policyengine.simple:
+  fixedGasPrice: null
+  gasOracle:
+    mode: connector
+
+

For more info about confirmations, see Public vs. Permissioned

+

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

+

Creating a new stack

+

To create a local FireFly development stack and connect it to the Polygon Mumbai testnet, we will use command line flags to customize the following settings:

+
    +
  • Create a new Ethereum based stack named polygon with 1 member
    • +
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
    • +
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
    • +
  • See the list of Polygon RPC endpoints and select an HTTPS RPC endpoint.
    • +
  • Set the chain ID to 80001 (the correct ID for the Polygon Mumbai testnet)
    • +
  • Merge the custom config created above with the generated evmconnect config file
    • +
+

To do this, run the following command:

+
ff init ethereum polygon 1 \
+    --multiparty=false \
+    -n remote-rpc \
+    --remote-node-url <selected RPC endpoint> \
+    --chain-id 80001 \
+    --connector-config ~/Desktop/evmconnect.yml
+
+

Start the stack

+

Now you should be able to start your stack by running:

+
ff start polygon
+
+

After some time it should print out the following:

+
Web UI for member '0': http://127.0.0.1:5000/ui
+Sandbox UI for member '0': http://127.0.0.1:5109
+
+
+To see logs for your stack run:
+
+ff logs polygon
+
+

Get some MATIC

+

At this point you should have a working FireFly stack, talking to a public chain. However, you won't be able to run any transactions just yet, because you don't have any way to pay for gas. A testnet faucet can give us some MATIC, the native token for Polygon.

+

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

+
ff accounts list polygon
+[
+  {
+    "address": "0x02d42c32a97c894486afbc7b717edff50c70b292",
+    "privateKey": "..."
+  }
+]
+
+

Copy the address listed in the output from this command. Go to https://faucet.polygon.technology/ and paste the address in the form. Click the Submit button, and then Confirm.

+

Polygon Faucet

+

Confirm the transaction on Polygonscan

+

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.

+

You can also click on the Internal Txns tab from you account page to see the actual transfer of the MATIC from the faucet.

+

Polygonscan

+

Use the public testnet

+

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.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/chains/tezos_testnet/index.html b/v1.3.1/tutorials/chains/tezos_testnet/index.html new file mode 100644 index 000000000..f89eeb706 --- /dev/null +++ b/v1.3.1/tutorials/chains/tezos_testnet/index.html @@ -0,0 +1,3634 @@ + + + + + + + + + + + + + + + + + + + + + + + Tezos Testnet - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Tezos Testnet

+ +

This guide will walk you through the steps to create a local FireFly development environment and connect it to the public Tezos Ghostnet testnet.

+

Previous steps: Install the FireFly CLI

+

If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to Install the FireFly CLI.

+

← ① Install the FireFly CLI

+

Set up the transaction signing service

+

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.

+
+

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.

+
+

Creating a new stack

+

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:

+
    +
  • Create a new Tezos based stack named tezos with 1 member
    • +
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
    • +
  • See the list of Tezos public RPC nodes and select an HTTPS RPC node.
    • +
+

To do this, run the following command:

+
ff init tezos dev 1 \
+    --multiparty=false \
+    --remote-node-url <selected RPC endpoint>
+
+
+

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.

+
+

Start the stack

+

Now you should be able to start your stack by running:

+
ff start dev
+
+

After some time it should print out the following:

+
Web UI for member '0': http://127.0.0.1:5000/ui
+Sandbox UI for member '0': http://127.0.0.1:5109
+
+
+To see logs for your stack run:
+
+ff logs dev
+
+

Get some XTZ

+

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.

+

First, you need to get an account address, which was created during signer set up step.\ +To check that, you can run:

+
ff accounts list dev
+[
+  {
+    "address": "tz1cuFw1E2Mn2bVS8q8d7QoCb6FXC18JivSp",
+    "privateKey": "..."
+  }
+]
+
+

After that, go to Tezos Ghostnet Faucet and paste the address in the form and click the Request button.

+

Tezos Faucet

+

Confirm the transaction on TzStats

+

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.

+

On the Transfers tab from you account page you will see the actual transfer of the XTZ from the faucet.

+

TzStats

+

Use the public testnet

+

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.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/chains/zksync_testnet/index.html b/v1.3.1/tutorials/chains/zksync_testnet/index.html new file mode 100644 index 000000000..0b7221a0f --- /dev/null +++ b/v1.3.1/tutorials/chains/zksync_testnet/index.html @@ -0,0 +1,3641 @@ + + + + + + + + + + + + + + + + + + + + + + + zkSync Testnet - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

zkSync Testnet

+ +

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.

+

Previous steps: Install the FireFly CLI

+

If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to Install the FireFly CLI.

+

← ① Install the FireFly CLI

+

Create an evmconnect.yml config file

+

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 evmconnect.yml with the following contents:

+
confirmations:
+  required: 4 # choose the number of confirmations you require
+policyengine.simple:
+  fixedGasPrice: null
+  gasOracle:
+    mode: connector
+
+

For this tutorial, we will assume this file is saved at ~/Desktop/evmconnect.yml. If your path is different, you will need to adjust the path in the next command below.

+

Creating a new stack

+

To create a local FireFly development stack and connect it to the zkSync testnet, we will use command line flags to customize the following settings:

+
    +
  • Create a new stack named zkSync with 1 member
    • +
  • Disable multiparty mode. We are going to be using this FireFly node as a Web3 gateway, and we don't need to communicate with a consortium here
    • +
  • Connect to an ethereum network
    • +
  • Use the evmconnect blockchain connector
    • +
  • Use an remote RPC node. This will create a signer locally, so that our signing key never leaves the development machine.
    • +
  • See the list of providers for zkSync docs. For this tutorial we will use https://zksync2-testnet.zksync.dev
    • +
  • Set the chain ID to 280 (the correct ID for the zkSync testnet)
    • +
  • Merge the custom config created above with the generated evmconnect config file
    • +
+

To do this, run the following command:

+
ff init zksync 1\
+    --multiparty=false \
+    -b ethereum \
+    -c evmconnect \
+    -n remote-rpc \
+    --remote-node-url https://zksync2-testnet.zksync.dev\
+    --chain-id 280 \
+    --connector-config ~/Desktop/evmconnect.yml
+
+

Start the stack

+

Now you should be able to start your stack by running:

+
ff start zksync
+
+

After some time it should print out the following:

+
Web UI for member '0': http://127.0.0.1:5000/ui
+Sandbox UI for member '0': http://127.0.0.1:5109
+
+
+To see logs for your stack run:
+
+ff logs zksync
+
+

Get some ETH

+

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.

+

First, you will need to know what signing address your FireFly node is using. To check that, you can run:

+
ff accounts list zkSync
+[
+  {
+    "address": "0x8cf4fd38b2d56a905113d23b5a7131f0269d8611",
+    "privateKey": "..."
+  }
+]
+
+

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.

+

Goerli Faucet

+

Confirm the transaction on the Etherscan Explorer

+

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.

+

Etherscan

+

Use the public testnet

+

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.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/create_custom_identity/index.html b/v1.3.1/tutorials/create_custom_identity/index.html new file mode 100644 index 000000000..f2b5f3d75 --- /dev/null +++ b/v1.3.1/tutorials/create_custom_identity/index.html @@ -0,0 +1,3816 @@ + + + + + + + + + + + + + + + + + + + + + + + Create a custom identity - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Create a Custom Identity

+

Quick reference

+

Out of the box, a FireFly Supernode contains both an org and a node 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.

+

Additional info

+ +

Previous steps: Start your environment

+

If you haven't started a FireFly stack already, please go to the Getting Started guide on how to Start your environment

+

← ② Start your environment

+

Step 1: Create a new account

+

The FireFly CLI has a helpful command to create an account in a local development environment for you.

+
+

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.

+
+

To create a new account on your local stack, run:

+
ff accounts create <stack_name>
+
+
{
+  "address": "0xc00109e112e21165c7065da776c75cfbc9cdc5e7",
+  "privateKey": "..."
+}
+
+

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.

+

Step 2: Query the parent org for its UUID

+

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 GET request to the status endpoint on the default namespace.

+

Request

+

GET http://localhost:5000/api/v1/status

+

Response

+
{
+    "namespace": {...},
+    "node": {...},
+    "org": {
+        "name": "org_0",
+        "registered": true,
+        "did": "did:firefly:org/org_0",
+        "id": "1c0abf75-0f3a-40e4-a8cd-5ff926f80aa8", // We need this in Step 3
+        "verifiers": [
+            {
+                "type": "ethereum_address",
+                "value": "0xd7320c76a2efc1909196dea876c4c7dabe49c0f4"
+            }
+        ]
+    },
+    "plugins": {...},
+    "multiparty": {...}
+}
+
+

Step 3: Register the new custom identity with FireFly

+

Now we can POST 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 "parent" field in the request.

+

Request

+

POST http://localhost:5000/api/v1/identities

+
{
+    "name": "myCustomIdentity",
+    "key": "0xc00109e112e21165c7065da776c75cfbc9cdc5e7", // Signing Key from Step 1
+    "parent": "1c0abf75-0f3a-40e4-a8cd-5ff926f80aa8" // Org UUID from Step 2
+}
+
+

Response

+
{
+    "id": "5ea8f770-e004-48b5-af60-01994230ed05",
+    "did": "did:firefly:myCustomIdentity",
+    "type": "custom",
+    "parent": "1c0abf75-0f3a-40e4-a8cd-5ff926f80aa8",
+    "namespace": "",
+    "name": "myCustomIdentity",
+    "messages": {
+        "claim": "817b7c79-a934-4936-bbb1-7dcc7c76c1f4",
+        "verification": "ae55f998-49b1-4391-bed2-fa5e86dc85a2",
+        "update": null
+    }
+}
+
+

Step 4: Query the New Custom Identity

+

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.

+

Request

+

GET http://localhost:5000/api/v1/identities?fetchverifiers=true

+
+

NOTE: Using fetchverifiers=true will return the cryptographic verification mechanism for the FireFly identity.

+
+

Response

+
[
+    {
+        "id": "5ea8f770-e004-48b5-af60-01994230ed05",
+        "did": "did:firefly:myCustomIdentity",
+        "type": "custom",
+        "parent": "1c0abf75-0f3a-40e4-a8cd-5ff926f80aa8",
+        "namespace": "default",
+        "name": "myCustomIdentity",
+        "messages": {
+            "claim": "817b7c79-a934-4936-bbb1-7dcc7c76c1f4",
+            "verification": "ae55f998-49b1-4391-bed2-fa5e86dc85a2",
+            "update": null
+        },
+        "created": "2022-09-19T18:10:47.365068013Z",
+        "updated": "2022-09-19T18:10:47.365068013Z",
+        "verifiers": [
+            {
+                "type": "ethereum_address",
+                "value": "0xfe1ea8c8a065a0cda424e2351707c7e8eb4d2b6f"
+            }
+        ]
+    },
+    { ... },
+    { ... }
+]
+
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/custom_contracts/ethereum/index.html b/v1.3.1/tutorials/custom_contracts/ethereum/index.html new file mode 100644 index 000000000..b7a62435e --- /dev/null +++ b/v1.3.1/tutorials/custom_contracts/ethereum/index.html @@ -0,0 +1,5229 @@ + + + + + + + + + + + + + + + + + + + + + + + Ethereum - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Work with Ethereum smart contracts

+

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.

+
+

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.

+
+

Example smart contract

+

For this tutorial, we will be using a well known, but slightly modified smart contract called SimpleStorage, 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.

+

Here is the source for this contract:

+
// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.10;
+
+// Declares a new contract
+contract SimpleStorage {
+    // Storage. Persists in between transactions
+    uint256 x;
+
+    // Allows the unsigned integer stored to be changed
+    function set(uint256 newValue) public {
+        x = newValue;
+        emit Changed(msg.sender, newValue);
+    }
+
+    // Returns the currently stored unsigned integer
+    function get() public view returns (uint256) {
+        return x;
+    }
+
+    event Changed(address indexed from, uint256 value);
+}
+
+

Contract deployment

+

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.

+

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.

+

Request

+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
keyThe signing key to use to dpeloy the contract. If omitted, the namespaces's default signing key will be used.
contractThe compiled bytecode for your smart contract. It should be either a hex encded string or Base64.
definitionThe full ABI JSON array from your compiled JSON file. Copy the entire value of the abi field from the [ to the ].
inputAn ordered list of constructor arguments. Some contracts may not require any (such as this example).
+

POST http://localhost:5000/api/v1/namespaces/default/contracts/deploy

+
{
+  "contract": "608060405234801561001057600080fd5b5061019e806100206000396000f3fe608060405234801561001057600080fd5b50600436106100365760003560e01c806360fe47b11461003b5780636d4ce63c14610057575b600080fd5b61005560048036038101906100509190610111565b610075565b005b61005f6100cd565b60405161006c919061014d565b60405180910390f35b806000819055503373ffffffffffffffffffffffffffffffffffffffff167fb52dda022b6c1a1f40905a85f257f689aa5d69d850e49cf939d688fbe5af5946826040516100c2919061014d565b60405180910390a250565b60008054905090565b600080fd5b6000819050919050565b6100ee816100db565b81146100f957600080fd5b50565b60008135905061010b816100e5565b92915050565b600060208284031215610127576101266100d6565b5b6000610135848285016100fc565b91505092915050565b610147816100db565b82525050565b6000602082019050610162600083018461013e565b9291505056fea2646970667358221220e6cbd7725b98b234d07bc1823b60ac065b567c6645d15c8f8f6986e5fa5317c664736f6c634300080b0033",
+  "definition": [
+    {
+      "anonymous": false,
+      "inputs": [
+        {
+          "indexed": true,
+          "internalType": "address",
+          "name": "from",
+          "type": "address"
+        },
+        {
+          "indexed": false,
+          "internalType": "uint256",
+          "name": "value",
+          "type": "uint256"
+        }
+      ],
+      "name": "Changed",
+      "type": "event"
+    },
+    {
+      "inputs": [],
+      "name": "get",
+      "outputs": [
+        {
+          "internalType": "uint256",
+          "name": "",
+          "type": "uint256"
+        }
+      ],
+      "stateMutability": "view",
+      "type": "function"
+    },
+    {
+      "inputs": [
+        {
+          "internalType": "uint256",
+          "name": "newValue",
+          "type": "uint256"
+        }
+      ],
+      "name": "set",
+      "outputs": [],
+      "stateMutability": "nonpayable",
+      "type": "function"
+    }
+  ],
+  "input": []
+}
+
+

Response

+
{
+  "id": "aa155a3c-2591-410e-bc9d-68ae7de34689",
+  "namespace": "default",
+  "tx": "4712ffb3-cc1a-4a91-aef2-206ac068ba6f",
+  "type": "blockchain_deploy",
+  "status": "Succeeded",
+  "plugin": "ethereum",
+  "input": {
+    "contract": "608060405234801561001057600080fd5b5061019e806100206000396000f3fe608060405234801561001057600080fd5b50600436106100365760003560e01c806360fe47b11461003b5780636d4ce63c14610057575b600080fd5b61005560048036038101906100509190610111565b610075565b005b61005f6100cd565b60405161006c919061014d565b60405180910390f35b806000819055503373ffffffffffffffffffffffffffffffffffffffff167fb52dda022b6c1a1f40905a85f257f689aa5d69d850e49cf939d688fbe5af5946826040516100c2919061014d565b60405180910390a250565b60008054905090565b600080fd5b6000819050919050565b6100ee816100db565b81146100f957600080fd5b50565b60008135905061010b816100e5565b92915050565b600060208284031215610127576101266100d6565b5b6000610135848285016100fc565b91505092915050565b610147816100db565b82525050565b6000602082019050610162600083018461013e565b9291505056fea2646970667358221220e6cbd7725b98b234d07bc1823b60ac065b567c6645d15c8f8f6986e5fa5317c664736f6c634300080b0033",
+    "definition": [
+      {
+        "anonymous": false,
+        "inputs": [
+          {
+            "indexed": true,
+            "internalType": "address",
+            "name": "from",
+            "type": "address"
+          },
+          {
+            "indexed": false,
+            "internalType": "uint256",
+            "name": "value",
+            "type": "uint256"
+          }
+        ],
+        "name": "Changed",
+        "type": "event"
+      },
+      {
+        "inputs": [],
+        "name": "get",
+        "outputs": [
+          {
+            "internalType": "uint256",
+            "name": "",
+            "type": "uint256"
+          }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+      },
+      {
+        "inputs": [
+          {
+            "internalType": "uint256",
+            "name": "newValue",
+            "type": "uint256"
+          }
+        ],
+        "name": "set",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+      }
+    ],
+    "input": [],
+    "key": "0xddd93a452bfc8d3e62bbc60c243046e4d0cb971b",
+    "options": null
+  },
+  "output": {
+    "headers": {
+      "requestId": "default:aa155a3c-2591-410e-bc9d-68ae7de34689",
+      "type": "TransactionSuccess"
+    },
+    "contractLocation": {
+      "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1"
+    },
+    "protocolId": "000000000024/000000",
+    "transactionHash": "0x32d1144091877266d7f0426e48db157e7d1a857c62e6f488319bb09243f0f851"
+  },
+  "created": "2023-02-03T15:42:52.750277Z",
+  "updated": "2023-02-03T15:42:52.750277Z"
+}
+
+

Here we can see in the response above under the output section that our new contract address is 0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1. This is the address that we will reference in the rest of this guide.

+

The FireFly Interface Format

+

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.

+

Request

+

Here we will take the JSON ABI generated by truffle or solc and POST that to FireFly to have it automatically generate the FireFly Interface for us. Copy the abi from the compiled JSON file, and put that inside an input object like the example below:

+

POST http://localhost:5000/api/v1/namespaces/default/contracts/interfaces/generate

+
{
+  "input": {
+    "abi": [
+      {
+        "anonymous": false,
+        "inputs": [
+          {
+            "indexed": true,
+            "internalType": "address",
+            "name": "from",
+            "type": "address"
+          },
+          {
+            "indexed": false,
+            "internalType": "uint256",
+            "name": "value",
+            "type": "uint256"
+          }
+        ],
+        "name": "Changed",
+        "type": "event"
+      },
+      {
+        "inputs": [],
+        "name": "get",
+        "outputs": [
+          {
+            "internalType": "uint256",
+            "name": "",
+            "type": "uint256"
+          }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+      },
+      {
+        "inputs": [
+          {
+            "internalType": "uint256",
+            "name": "newValue",
+            "type": "uint256"
+          }
+        ],
+        "name": "set",
+        "outputs": [],
+        "stateMutability": "nonpayable",
+        "type": "function"
+      }
+    ]
+  }
+}
+
+

Response

+

FireFly generates and returns the the full FireFly Interface for the SimpleStorage contract in the response body:

+
{
+  "namespace": "default",
+  "name": "",
+  "description": "",
+  "version": "",
+  "methods": [
+    {
+      "name": "get",
+      "pathname": "",
+      "description": "",
+      "params": [],
+      "returns": [
+        {
+          "name": "",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "uint256",
+              "internalType": "uint256"
+            }
+          }
+        }
+      ]
+    },
+    {
+      "name": "set",
+      "pathname": "",
+      "description": "",
+      "params": [
+        {
+          "name": "newValue",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "uint256",
+              "internalType": "uint256"
+            }
+          }
+        }
+      ],
+      "returns": []
+    }
+  ],
+  "events": [
+    {
+      "name": "Changed",
+      "description": "",
+      "params": [
+        {
+          "name": "from",
+          "schema": {
+            "type": "string",
+            "details": {
+              "type": "address",
+              "internalType": "address",
+              "indexed": true
+            }
+          }
+        },
+        {
+          "name": "value",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "uint256",
+              "internalType": "uint256"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+
+

Broadcast the contract interface

+

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.

+

We will take the output from the previous HTTP response above, fill in the name and version and then POST that to the /contracts/interfaces API endpoint.

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/contracts/interfaces?publish=true

+
+

NOTE: Without passing the query parameter publish=true 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 /contracts/interfaces/{name}/{version}/publish

+
+
{
+  "namespace": "default",
+  "name": "SimpleStorage",
+  "version": "v1.0.0",
+  "description": "",
+  "methods": [
+    {
+      "name": "get",
+      "pathname": "",
+      "description": "",
+      "params": [],
+      "returns": [
+        {
+          "name": "",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "uint256",
+              "internalType": "uint256"
+            }
+          }
+        }
+      ]
+    },
+    {
+      "name": "set",
+      "pathname": "",
+      "description": "",
+      "params": [
+        {
+          "name": "newValue",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "uint256",
+              "internalType": "uint256"
+            }
+          }
+        }
+      ],
+      "returns": []
+    }
+  ],
+  "events": [
+    {
+      "name": "Changed",
+      "description": "",
+      "params": [
+        {
+          "name": "from",
+          "schema": {
+            "type": "string",
+            "details": {
+              "type": "address",
+              "internalType": "address",
+              "indexed": true
+            }
+          }
+        },
+        {
+          "name": "value",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "uint256",
+              "internalType": "uint256"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+
+

Response

+
{
+  "id": "8bdd27a5-67c1-4960-8d1e-7aa31b9084d3",
+  "message": "3cd0dde2-1e39-4c9e-a4a1-569e87cca93a",
+  "namespace": "default",
+  "name": "SimpleStorage",
+  "description": "",
+  "version": "v1.0.0",
+  "methods": [
+    {
+      "id": "56467890-5713-4463-84b8-4537fcb63d8b",
+      "contract": "8bdd27a5-67c1-4960-8d1e-7aa31b9084d3",
+      "name": "get",
+      "namespace": "default",
+      "pathname": "get",
+      "description": "",
+      "params": [],
+      "returns": [
+        {
+          "name": "",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "uint256",
+              "internalType": "uint256"
+            }
+          }
+        }
+      ]
+    },
+    {
+      "id": "6b254d1d-5f5f-491e-bbd2-201e96892e1a",
+      "contract": "8bdd27a5-67c1-4960-8d1e-7aa31b9084d3",
+      "name": "set",
+      "namespace": "default",
+      "pathname": "set",
+      "description": "",
+      "params": [
+        {
+          "name": "newValue",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "uint256",
+              "internalType": "uint256"
+            }
+          }
+        }
+      ],
+      "returns": []
+    }
+  ],
+  "events": [
+    {
+      "id": "aa1fe67b-b2ac-41af-a7e7-7ad54a30a78d",
+      "contract": "8bdd27a5-67c1-4960-8d1e-7aa31b9084d3",
+      "namespace": "default",
+      "pathname": "Changed",
+      "name": "Changed",
+      "description": "",
+      "params": [
+        {
+          "name": "from",
+          "schema": {
+            "type": "string",
+            "details": {
+              "type": "address",
+              "internalType": "address",
+              "indexed": true
+            }
+          }
+        },
+        {
+          "name": "value",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "uint256",
+              "internalType": "uint256"
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "published": true
+}
+
+

Create an HTTP API for the contract

+

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.

+

We need to copy the id field we got in the response from the previous step to the interface.id 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 simple-storage. Lastly, in the location.address field, we're telling FireFly where an instance of the contract is deployed on-chain.

+
+

NOTE: The location 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.

+
+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/apis?publish=true

+
+

NOTE: Without passing the query parameter publish=true 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 /apis/{apiName}/publish

+
+
{
+  "name": "simple-storage",
+  "interface": {
+    "id": "8bdd27a5-67c1-4960-8d1e-7aa31b9084d3"
+  },
+  "location": {
+    "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1"
+  }
+}
+
+

Response

+
{
+  "id": "9a681ec6-1dee-42a0-b91b-61d23a814b0f",
+  "namespace": "default",
+  "interface": {
+    "id": "8bdd27a5-67c1-4960-8d1e-7aa31b9084d3"
+  },
+  "location": {
+    "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1"
+  },
+  "name": "simple-storage",
+  "message": "d90d0386-8874-43fb-b7d3-485c22f35f47",
+  "urls": {
+    "openapi": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api/swagger.json",
+    "ui": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api"
+  },
+  "published": true
+}
+
+

View OpenAPI spec for the contract

+

You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled ui in your browser, you should see the Swagger UI for your smart contract.

+

Swagger UI

+

Invoke the smart contract

+

Now that we've got everything set up, it's time to use our smart contract! We're going to make a POST request to the invoke/set endpoint to set the integer value on-chain. Let's set it to the value of 3 right now.

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set

+
{
+  "input": {
+    "newValue": 3
+  }
+}
+
+

Response

+
{
+  "id": "41c67c63-52cf-47ce-8a59-895fe2ffdc86"
+}
+
+

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.

+

Query the current value

+

To make a read-only request to the blockchain to check the current value of the stored integer, we can make a POST to the query/get endpoint.

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/query/get

+
{}
+
+

Response

+
{
+  "output": "3"
+}
+
+
+

NOTE: Some contracts may have queries that require input parameters. That's why the query endpoint is a POST, rather than a GET 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.

+
+

Passing additional options with a request

+

Some smart contract functions may accept or require additional options to be passed with the request. For example, a Solidity function might be payable, meaning that a value field must be specified, indicating an amount of ETH to be transferred with the request. Each of your smart contract API's /invoke or /query endpoints support an options object in addition to the input arguments for the function itself.

+

Here is an example of sending 100 wei with a transaction:

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set

+
{
+  "input": {
+    "newValue": 3
+  },
+  "options": {
+    "value": 100
+  }
+}
+
+

Response

+
{
+  "id": "41c67c63-52cf-47ce-8a59-895fe2ffdc86"
+}
+
+

Create a blockchain event listener

+

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.

+

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 /contracts/listeners endpoint is RESTful so there are POST, GET, and DELETE methods available on it. To create a new listener, we will make a POST request. We are going to tell FireFly to listen to events with name "Changed" 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.

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/contracts/listeners

+
{
+  "filters": [
+    {
+      "interface": {
+        "id": "8bdd27a5-67c1-4960-8d1e-7aa31b9084d3"
+      },
+      "location": {
+        "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1"
+      },
+      "eventPath": "Changed"
+    }
+  ],
+  "options": {
+    "firstEvent": "newest"
+  },
+  "topic": "simple-storage"
+}
+
+

Response

+
{
+  "id": "e7c8457f-4ffd-42eb-ac11-4ad8aed30de1",
+  "interface": {
+    "id": "55fdb62a-fefc-4313-99e4-e3f95fcca5f0"
+  },
+  "namespace": "default",
+  "name": "019104d7-bb0a-c008-76a9-8cb923d91b37",
+  "backendId": "019104d7-bb0a-c008-76a9-8cb923d91b37",
+  "location": {
+    "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1"
+  },
+  "created": "2024-07-30T18:12:12.704964Z",
+  "event": {
+    "name": "Changed",
+    "description": "",
+    "params": [
+      {
+        "name": "from",
+        "schema": {
+          "type": "string",
+          "details": {
+            "type": "address",
+            "internalType": "address",
+            "indexed": true
+          }
+        }
+      },
+      {
+        "name": "value",
+        "schema": {
+          "type": "integer",
+          "details": {
+            "type": "uint256",
+            "internalType": "uint256"
+          }
+        }
+      }
+    ]
+  },
+  "signature": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]",
+  "topic": "simple-storage",
+  "options": {
+    "firstEvent": "newest"
+  },
+  "filters": [
+    {
+      "event": {
+        "name": "Changed",
+        "description": "",
+        "params": [
+          {
+            "name": "from",
+            "schema": {
+              "type": "string",
+              "details": {
+                "type": "address",
+                "internalType": "address",
+                "indexed": true
+              }
+            }
+          },
+          {
+            "name": "value",
+            "schema": {
+              "type": "integer",
+              "details": {
+                "type": "uint256",
+                "internalType": "uint256"
+              }
+            }
+          }
+        ]
+      },
+      "location": {
+        "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1"
+      },
+      "interface": {
+        "id": "55fdb62a-fefc-4313-99e4-e3f95fcca5f0"
+      },
+      "signature": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1:Changed(address,uint256) [i=0]"
+    }
+  ]
+}
+
+

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.

+

Querying listener status

+

If you are interested in learning about the current state of a listener you have created, you can query with the fetchstatus 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.

+

Request / Response

+

GET http://localhost:5000/api/v1/namespaces/default/contracts/listeners/1bfa3b0f-3d90-403e-94a4-af978d8c5b14?fetchstatus

+
{
+  "id": "1bfa3b0f-3d90-403e-94a4-af978d8c5b14",
+  "interface": {
+    "id": "8bdd27a5-67c1-4960-8d1e-7aa31b9084d3"
+  },
+  "namespace": "default",
+  "name": "sb-66209ffc-d355-4ac0-7151-bc82490ca9df",
+  "protocolId": "sb-66209ffc-d355-4ac0-7151-bc82490ca9df",
+  "location": {
+    "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1"
+  },
+  "created": "2022-02-17T22:02:36.34549538Z",
+  "event": {
+    "name": "Changed",
+    "description": "",
+    "params": [
+      {
+        "name": "from",
+        "schema": {
+          "type": "string",
+          "details": {
+            "type": "address",
+            "internalType": "address",
+            "indexed": true
+          }
+        }
+      },
+      {
+        "name": "value",
+        "schema": {
+          "type": "integer",
+          "details": {
+            "type": "uint256",
+            "internalType": "uint256"
+          }
+        }
+      }
+    ]
+  },
+  "status": {
+    "checkpoint": {
+      "block": 0,
+      "transactionIndex": -1,
+      "logIndex": -1
+    },
+    "catchup": true
+  },
+  "options": {
+    "firstEvent": "oldest"
+  }
+}
+
+

Subscribe to events from our contract

+

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 POST to the /subscriptions endpoint.

+

We will set a friendly name simple-storage to identify the Subscription when we are connecting to it in the next step.

+

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 (1bfa3b0f-3d90-403e-94a4-af978d8c5b14) and set that as the value of the listener field in the example below:

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/subscriptions

+
{
+  "namespace": "default",
+  "name": "simple-storage",
+  "transport": "websockets",
+  "filter": {
+    "events": "blockchain_event_received",
+    "blockchainevent": {
+      "listener": "1bfa3b0f-3d90-403e-94a4-af978d8c5b14"
+    }
+  },
+  "options": {
+    "firstEvent": "oldest"
+  }
+}
+
+

Response

+
{
+  "id": "f826269c-65ed-4634-b24c-4f399ec53a32",
+  "namespace": "default",
+  "name": "simple-storage",
+  "transport": "websockets",
+  "filter": {
+    "events": "blockchain_event_received",
+    "message": {},
+    "transaction": {},
+    "blockchainevent": {
+      "listener": "1bfa3b0f-3d90-403e-94a4-af978d8c5b14"
+    }
+  },
+  "options": {
+    "firstEvent": "-1",
+    "withData": false
+  },
+  "created": "2022-03-15T17:35:30.131698921Z",
+  "updated": null
+}
+
+

Receive custom smart contract events

+

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

+

Connect your WebSocket client to ws://localhost:5000/ws.

+

After connecting the WebSocket client, send a message to tell FireFly to:

+
    +
  • Start sending events
    • +
  • For the Subscription named simple-storage
    • +
  • On the default namespace
    • +
  • Automatically "ack" each event which will let FireFly immediately send the next event when available
    • +
+
{
+  "type": "start",
+  "name": "simple-storage",
+  "namespace": "default",
+  "autoack": true
+}
+
+

WebSocket event

+

After creating the subscription, you should see an event arrive on the connected WebSocket client that looks something like this:

+
{
+  "id": "0f4a31d6-9743-4537-82df-5a9c76ccbd1e",
+  "sequence": 24,
+  "type": "blockchain_event_received",
+  "namespace": "default",
+  "reference": "dd3e1554-c832-47a8-898e-f1ee406bea41",
+  "created": "2022-03-15T17:32:27.824417878Z",
+  "blockchainevent": {
+    "id": "dd3e1554-c832-47a8-898e-f1ee406bea41",
+    "sequence": 7,
+    "source": "ethereum",
+    "namespace": "default",
+    "name": "Changed",
+    "listener": "1bfa3b0f-3d90-403e-94a4-af978d8c5b14",
+    "protocolId": "000000000010/000000/000000",
+    "output": {
+      "from": "0xb7e6a5eb07a75a2c81801a157192a82bcbce0f21",
+      "value": "3"
+    },
+    "info": {
+      "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1",
+      "blockNumber": "10",
+      "logIndex": "0",
+      "signature": "Changed(address,uint256)",
+      "subId": "sb-724b8416-786d-4e67-4cd3-5bae4a26eb0e",
+      "timestamp": "1647365460",
+      "transactionHash": "0xd5b5c716554097b2868d8705241bb2189bb76d16300f702ad05b0b02fccc4afb",
+      "transactionIndex": "0x0"
+    },
+    "timestamp": "2022-03-15T17:31:00Z",
+    "tx": {
+      "type": ""
+    }
+  },
+  "subscription": {
+    "id": "f826269c-65ed-4634-b24c-4f399ec53a32",
+    "namespace": "default",
+    "name": "simple-storage"
+  }
+}
+
+

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 "firstEvent" as "oldest". 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.

+

In the event, we can also see the blockchainevent itself, which has an output object. These are the params in our FireFly Interface, and the actual output of the event. Here we can see the value is 3 which is what we set the integer to in our original transaction.

+

Subscription offset

+

If you query by the ID of your subscription with the fetchstatus parameter, you can see its current offset.

+

GET http://localhost:5000/api/v1/namespaces/default/subscriptions/f826269c-65ed-4634-b24c-4f399ec53a32

+
{
+  "id": "f826269c-65ed-4634-b24c-4f399ec53a32",
+  "namespace": "default",
+  "name": "simple-storage",
+  "transport": "websockets",
+  "filter": {
+    "events": "blockchain_event_received",
+    "message": {},
+    "transaction": {},
+    "blockchainevent": {
+      "listener": "1bfa3b0f-3d90-403e-94a4-af978d8c5b14"
+    }
+  },
+  "options": {
+    "firstEvent": "-1",
+    "withData": false
+  },
+  "status": {
+    "offset": 20
+  }
+  "created": "2022-03-15T17:35:30.131698921Z",
+  "updated": null
+}
+
+

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.

+

Appendix I: Work with a custom contract without creating a named API

+

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.

+

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:

+
    +
  • OpenAPI Spec and Swagger UI are not available
    • +
  • Each HTTP request to invoke/query the contract will need to include the contract location
    • +
  • The contract location will not have been broadcasted to all other members of the network
    • +
  • The URL to invoke/query the contract will be different (described below)
    • +
+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/contracts/interfaces/8bdd27a5-67c1-4960-8d1e-7aa31b9084d3/invoke/set

+
{
+  "location": {
+    "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1"
+  },
+  "input": {
+    "newValue": 7
+  }
+}
+
+

Response

+
{
+  "id": "f310fa4a-73d8-4777-9f9d-dfa5012a052f"
+}
+
+

All of the same invoke, query, and subscribe endpoints are available on the contract interface itself.

+

Appendix II: Work directly with contracts with inline requests

+

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.

+

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.

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/contracts/invoke

+
{
+  "location": {
+    "address": "0xa5ea5d0a6b2eaf194716f0cc73981939dca26da1"
+  },
+  "method": {
+    "name": "set",
+    "params": [
+      {
+        "name": "x",
+        "schema": {
+          "type": "integer",
+          "details": {
+            "type": "uint256"
+          }
+        }
+      }
+    ],
+    "returns": []
+  },
+  "input": {
+    "x": 42
+  }
+}
+
+

Response

+
{
+  "id": "386d3e23-e4bc-4a9b-bc1f-452f0a8c9ae5"
+}
+
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/custom_contracts/fabric/index.html b/v1.3.1/tutorials/custom_contracts/fabric/index.html new file mode 100644 index 000000000..75dc18cff --- /dev/null +++ b/v1.3.1/tutorials/custom_contracts/fabric/index.html @@ -0,0 +1,4750 @@ + + + + + + + + + + + + + + + + + + + + + + + Fabric - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Work with Hyperledger Fabric chaincodes

+

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.

+
+

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.

+
+

Example smart contract

+

For this tutorial, we will be using a well known, but slightly modified smart contract called asset_transfer. It's based on the asset-transfer-basic 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 fabric-samples/asset-transfer-basic/chaincode-go/chaincode/smartcontract.go.

+

Find the following return statement in the function CreateAsset:

+
    return ctx.GetStub().PutState(id, assetJSON)
+
+

and replace it with the following, so that an event will be emitted when the transaction is committed to the channel ledger:

+
  err = ctx.GetStub().PutState(id, assetJSON)
+  if err != nil {
+    return err
+  }
+  return ctx.GetStub().SetEvent("AssetCreated", assetJSON)
+
+

Create the chaincode package

+

Use the peer 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.

+
  ~ johndoe$ cd fabric-samples/asset-transfer-basic/chaincode-go
+  chaincode-go johndoe$ touch core.yaml
+  chaincode-go johndoe$ peer lifecycle chaincode package -p . --label asset_transfer ./asset_transfer.zip
+
+
+

The peer command requires an empty core.yaml file to be present in the working directory to perform the packaging. That's what touch core.yaml did above

+
+

The resulting asset_transfer.zip archive file will be used in the next step to deploy to the Fabric network used in FireFly.

+

Contract deployment

+

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.

+

The FireFly CLI provides a convenient function to deploy a chaincode package to a local FireFly stack.

+
+

NOTE: The contract deployment function of the FireFly CLI is a convenience function to speed up local development, and not intended for production applications

+
+
~ johndoe$ ff help deploy fabric
+Deploy a packaged chaincode to the Fabric network used by a FireFly stack
+
+Usage:
+  ff deploy fabric <stack_name> <chaincode_package> <channel> <chaincodeName> <version> [flags]
+
+

Notice the various parameters used by the command ff deploy fabric. We'll tell the FireFly to deploy using the following parameter values, if your stack setup is different, update the command accordingly:

+
    +
  • stack name: dev
    • +
  • channel: firefly (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)
    • +
  • chaincode name: asset_transfer (must match the value of the --label parameter when creating the chaincode package)
    • +
  • version: 1.0
    • +
+
$ ff deploy fabric dev asset_transfer.zip firefly asset_transfer 1.0
+installing chaincode
+querying installed chaincode
+approving chaincode
+committing chaincode
+{
+  "chaincode": "asset_transfer",
+  "channel": "firefly"
+}
+
+

The FireFly Interface Format

+

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.

+

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:

+
    +
  • structured JSON, used here for the list of chaincode function CreateAsset input parameters
    • +
  • array of JSON, used here for the chaincode function GetAllAssets output
    • +
  • structured JSON, used here for the list of chaincode event AssetCreated properties
    • +
+
{
+  "namespace": "default",
+  "name": "asset_transfer",
+  "description": "Spec interface for the asset-transfer-basic golang chaincode",
+  "version": "1.0",
+  "methods": [
+    {
+      "name": "GetAllAssets",
+      "pathname": "",
+      "description": "",
+      "params": [],
+      "returns": [
+        {
+          "name": "",
+          "schema": {
+            "type": "array",
+            "details": {
+              "type": "object",
+              "properties": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      ]
+    },
+    {
+      "name": "CreateAsset",
+      "pathname": "",
+      "description": "",
+      "params": [
+        {
+          "name": "id",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "color",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "size",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "owner",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "value",
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "returns": []
+    }
+  ],
+  "events": [
+    {
+      "name": "AssetCreated"
+    }
+  ]
+}
+
+

Input parameters

+

For the params section of the CreateAsset function, it is critical that the sequence of the properties (id, color, size, owner, value) matches the order of the input parameters in the chaincode's function signature:

+
func CreateAsset(ctx contractapi.TransactionContextInterface, id string, color string, size int, owner string, appraisedValue int) error
+
+

Return values

+

FireFly can automatically decode JSON payloads in the return values. That's why the returns section of the GetAllAssets function only needs to specify the type as array of objects, without having to specify the detailed structure of the JSON payload.

+

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 AppraisedValue is omitted from the output.

+

Event payloads

+

For events, FireFly automatically decodes JSON payloads. If the event payload is not JSON, base64 encoded bytes will be returned instead. For the events section of the FFI, only the name property needs to be specified.

+

Broadcast the contract interface

+

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.

+

We will use the FFI JSON constructed above and POST that to the /contracts/interfaces API endpoint.

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/contracts/interfaces?publish=true

+
+

NOTE: Without passing the query parameter publish=true 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 /contracts/interfaces/{name}/{version}/publish

+
+
{
+  "namespace": "default",
+  "name": "asset_transfer",
+  "description": "Spec interface for the asset-transfer-basic golang chaincode",
+  "version": "1.0",
+  "methods": [
+    {
+      "name": "GetAllAssets",
+      "pathname": "",
+      "description": "",
+      "params": [],
+      "returns": [
+        {
+          "name": "",
+          "schema": {
+            "type": "array",
+            "details": {
+              "type": "object",
+              "properties": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      ]
+    },
+    {
+      "name": "CreateAsset",
+      "pathname": "",
+      "description": "",
+      "params": [
+        {
+          "name": "id",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "color",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "size",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "owner",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "value",
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "returns": []
+    }
+  ],
+  "events": [
+    {
+      "name": "AssetCreated"
+    }
+  ]
+}
+
+

Response

+
{
+  "id": "f1e5522c-59a5-4787-bbfd-89975e5b0954",
+  "message": "8a01fc83-5729-418b-9706-6fc17c8d2aac",
+  "namespace": "default",
+  "name": "asset_transfer",
+  "description": "Spec interface for the asset-transfer-basic golang chaincode",
+  "version": "1.1",
+  "methods": [
+    {
+      "id": "b31e3623-35e8-4918-bf8c-1b0d6c01de25",
+      "interface": "f1e5522c-59a5-4787-bbfd-89975e5b0954",
+      "name": "GetAllAssets",
+      "namespace": "default",
+      "pathname": "GetAllAssets",
+      "description": "",
+      "params": [],
+      "returns": [
+        {
+          "name": "",
+          "schema": {
+            "type": "array",
+            "details": {
+              "type": "object",
+              "properties": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      ]
+    },
+    {
+      "id": "e5a170d1-0be1-4697-800b-f4bcfaf71cf6",
+      "interface": "f1e5522c-59a5-4787-bbfd-89975e5b0954",
+      "name": "CreateAsset",
+      "namespace": "default",
+      "pathname": "CreateAsset",
+      "description": "",
+      "params": [
+        {
+          "name": "id",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "color",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "size",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "owner",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "value",
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "returns": []
+    }
+  ],
+  "events": [
+    {
+      "id": "27564533-30bd-4536-884e-02e5d79ec238",
+      "interface": "f1e5522c-59a5-4787-bbfd-89975e5b0954",
+      "namespace": "default",
+      "pathname": "AssetCreated",
+      "signature": "",
+      "name": "AssetCreated",
+      "description": "",
+      "params": null
+    }
+  ]
+}
+
+
+

NOTE: We can broadcast this contract interface conveniently with the help of FireFly Sandbox running at http://127.0.0.1:5108

+
+
    +
  • Go to the Contracts Section
    • +
  • Click on Define a Contract Interface
    • +
  • Select FFI - FireFly Interface in the Interface Fromat dropdown
    • +
  • Copy the FFI JSON crafted by you into the Schema Field
    • +
  • Click on Run
    • +
+

Create an HTTP API for the contract

+

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.

+

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.

+

We need to copy the id field we got in the response from the previous step to the interface.id 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 asset_transfer. Lastly, in the location field, we're telling FireFly where an instance of the chaincode is deployed on-chain, which is a chaincode named asset_transfer in the channel firefly.

+
+

NOTE: The location 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.

+
+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/apis?publish=true

+
+

NOTE: Without passing the query parameter publish=true 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 /apis/{apiName}/publish

+
+
{
+  "name": "asset_transfer",
+  "interface": {
+    "id": "f1e5522c-59a5-4787-bbfd-89975e5b0954"
+  },
+  "location": {
+    "channel": "firefly",
+    "chaincode": "asset_transfer"
+  }
+}
+
+

Response

+
{
+  "id": "a9a9ab4e-2544-45d5-8824-3c05074fbf75",
+  "namespace": "default",
+  "interface": {
+    "id": "f1e5522c-59a5-4787-bbfd-89975e5b0954"
+  },
+  "location": {
+    "channel": "firefly",
+    "chaincode": "asset_transfer"
+  },
+  "name": "asset_transfer",
+  "message": "5f1556a1-5cb1-4bc6-8611-d8f88ccf9c30",
+  "urls": {
+    "openapi": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/asset_transfer/api/swagger.json",
+    "ui": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/asset_transfer/api"
+  }
+}
+
+
+

NOTE: We can create this Http API conveniently with the help of FireFly Sandbox running at http://127.0.0.1:5108

+
+
    +
  • Go to the Contracts Section
    • +
  • Click on Register a Contract API
    • +
  • Select the name of your broadcasted FFI in the Contract Interface dropdown
    • +
  • In the Name Field, give a name that will be part of the URL for your Http API
    • +
  • In the Chaincode Field, give your chaincode name for which you wrote the FFI
    • +
  • In the Channel Field, give the channel name where your chaincode is deployed
    • +
  • Click on Run
    • +
+

View OpenAPI spec for the contract

+

You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled ui in your browser, you should see the Swagger UI for your chaincode.

+

Swagger UI

+

/invoke/* endpoints

+

The /invoke endpoints in the generated API are for submitting transactions. These endpoints will be mapped to the POST /transactions endpoint of the FabConnect API.

+

/query/* endpoints

+

The /query endpoints in the generated API, on the other hand, are for sending query requests. These endpoints will be mapped to the POST /query 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.

+

Invoke the chaincode

+

Now that we've got everything set up, it's time to use our chaincode! We're going to make a POST request to the invoke/CreateAsset endpoint to create a new asset.

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/apis/asset_transfer/invoke/CreateAsset

+
{
+  "input": {
+    "color": "blue",
+    "id": "asset-01",
+    "owner": "Harry",
+    "size": "30",
+    "value": "23400"
+  }
+}
+
+

Response

+
{
+  "id": "b8e905cc-bc23-434a-af7d-13c6d85ae545",
+  "namespace": "default",
+  "tx": "79d2668e-4626-4634-9448-1b40fa0d9dfd",
+  "type": "blockchain_invoke",
+  "status": "Pending",
+  "plugin": "fabric",
+  "input": {
+    "input": {
+      "color": "blue",
+      "id": "asset-02",
+      "owner": "Harry",
+      "size": "30",
+      "value": "23400"
+    },
+    "interface": "f1e5522c-59a5-4787-bbfd-89975e5b0954",
+    "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",
+    "location": {
+      "chaincode": "asset_transfer",
+      "channel": "firefly"
+    },
+    "method": {
+      "description": "",
+      "id": "e5a170d1-0be1-4697-800b-f4bcfaf71cf6",
+      "interface": "f1e5522c-59a5-4787-bbfd-89975e5b0954",
+      "name": "CreateAsset",
+      "namespace": "default",
+      "params": [
+        {
+          "name": "id",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "color",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "size",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "owner",
+          "schema": {
+            "type": "string"
+          }
+        },
+        {
+          "name": "value",
+          "schema": {
+            "type": "string"
+          }
+        }
+      ],
+      "pathname": "CreateAsset",
+      "returns": []
+    },
+    "methodPath": "CreateAsset",
+    "type": "invoke"
+  },
+  "created": "2022-05-02T17:08:40.811630044Z",
+  "updated": "2022-05-02T17:08:40.811630044Z"
+}
+
+

You'll notice that we got an ID back with status Pending, 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.

+

Query the current state

+

To make a read-only request to the blockchain to check the current list of assets, we can make a POST to the query/GetAllAssets endpoint.

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/apis/asset_transfer/query/GetAllAssets

+
{}
+
+

Response

+
[
+  {
+    "AppraisedValue": 23400,
+    "Color": "blue",
+    "ID": "asset-01",
+    "Owner": "Harry",
+    "Size": 30
+  }
+]
+
+
+

NOTE: Some chaincodes may have queries that require input parameters. That's why the query endpoint is a POST, rather than a GET 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.

+
+

Create a blockchain event listener

+

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.

+

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.

+

The /contracts/listeners endpoint is RESTful so there are POST, GET, and DELETE methods available on it. To create a new listener, we will make a POST request. We are going to tell FireFly to listen to events with name "AssetCreated" 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.

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/contracts/listeners

+
{
+  "filters": [
+    {
+      "interface": {
+        "id": "f1e5522c-59a5-4787-bbfd-89975e5b0954"
+      },
+      "location": {
+        "channel": "firefly",
+        "chaincode": "asset_transfer"
+      },
+      "event": {
+        "name": "AssetCreated"
+      }
+    }
+  ],
+  "options": {
+    "firstEvent": "oldest"
+  },
+  "topic": "assets"
+}
+
+

Response

+
{
+  "id": "d6b5e774-c9e5-474c-9495-ec07fa47a907",
+  "namespace": "default",
+  "name": "sb-44aa348a-bafb-4243-594e-dcad689f1032",
+  "backendId": "sb-44aa348a-bafb-4243-594e-dcad689f1032",
+  "location": {
+    "channel": "firefly",
+    "chaincode": "asset_transfer"
+  },
+  "created": "2024-07-22T15:36:58.514085959Z",
+  "event": {
+    "name": "AssetCreated",
+    "description": "",
+    "params": null
+  },
+  "signature": "firefly-asset_transfer:AssetCreated",
+  "topic": "assets",
+  "options": {
+    "firstEvent": "oldest"
+  },
+  "filters": [
+    {
+      "event": {
+        "name": "AssetCreated",
+        "description": "",
+        "params": null
+      },
+      "location": {
+        "channel": "firefly",
+        "chaincode": "asset_transfer"
+      },
+      "signature": "firefly-asset_transfer:AssetCreated"
+    }
+  ]
+}
+
+

Subscribe to events from our contract

+

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 POST to the /subscriptions endpoint.

+

We will set a friendly name asset_transfer to identify the Subscription when we are connecting to it in the next step.

+

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 (6e7f5dd8-5a57-4163-a1d2-5654e784dc31) and set that as the value of the listener field in the example below:

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/subscriptions

+
{
+  "namespace": "default",
+  "name": "asset_transfer",
+  "transport": "websockets",
+  "filter": {
+    "events": "blockchain_event_received",
+    "blockchainevent": {
+      "listener": "6e7f5dd8-5a57-4163-a1d2-5654e784dc31"
+    }
+  },
+  "options": {
+    "firstEvent": "oldest"
+  }
+}
+
+

Response

+
{
+  "id": "06d18b49-e763-4f5c-9e97-c25024fe57c8",
+  "namespace": "default",
+  "name": "asset_transfer",
+  "transport": "websockets",
+  "filter": {
+    "events": "blockchain_event_received",
+    "message": {},
+    "transaction": {},
+    "blockchainevent": {
+      "listener": "6e7f5dd8-5a57-4163-a1d2-5654e784dc31"
+    }
+  },
+  "options": {
+    "firstEvent": "-1",
+    "withData": false
+  },
+  "created": "2022-05-02T17:22:06.480181291Z",
+  "updated": null
+}
+
+

Receive custom smart contract events

+

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

+

Connect your WebSocket client to ws://localhost:5000/ws.

+

After connecting the WebSocket client, send a message to tell FireFly to:

+
    +
  • Start sending events
    • +
  • For the Subscription named asset_transfer
    • +
  • On the default namespace
    • +
  • Automatically "ack" each event which will let FireFly immediately send the next event when available
    • +
+
{
+  "type": "start",
+  "name": "asset_transfer",
+  "namespace": "default",
+  "autoack": true
+}
+
+

WebSocket event

+

After creating the subscription, you should see an event arrive on the connected WebSocket client that looks something like this:

+
{
+  "id": "d9fb86b2-b25b-43b8-80d3-936c5daa5a66",
+  "sequence": 29,
+  "type": "blockchain_event_received",
+  "namespace": "default",
+  "reference": "e0d670b4-a1b6-4efd-a985-06dfaaa58fe3",
+  "topic": "assets",
+  "created": "2022-05-02T17:26:57.57612001Z",
+  "blockchainEvent": {
+    "id": "e0d670b4-a1b6-4efd-a985-06dfaaa58fe3",
+    "source": "fabric",
+    "namespace": "default",
+    "name": "AssetCreated",
+    "listener": "6e7f5dd8-5a57-4163-a1d2-5654e784dc31",
+    "protocolId": "000000000015/000000/000000",
+    "output": {
+      "AppraisedValue": 12300,
+      "Color": "red",
+      "ID": "asset-01",
+      "Owner": "Jerry",
+      "Size": 10
+    },
+    "info": {
+      "blockNumber": 15,
+      "chaincodeId": "asset_transfer",
+      "eventIndex": 0,
+      "eventName": "AssetCreated",
+      "subId": "sb-2cac2bfa-38af-4408-4ff3-973421410e5d",
+      "timestamp": 1651512414920972300,
+      "transactionId": "172637bf59a3520ca6dd02f716e1043ba080e10e1cd2f98b4e6b85abcc6a6d69",
+      "transactionIndex": 0
+    },
+    "timestamp": "2022-05-02T17:26:54.9209723Z",
+    "tx": {
+      "type": "",
+      "blockchainId": "172637bf59a3520ca6dd02f716e1043ba080e10e1cd2f98b4e6b85abcc6a6d69"
+    }
+  },
+  "subscription": {
+    "id": "06d18b49-e763-4f5c-9e97-c25024fe57c8",
+    "namespace": "default",
+    "name": "asset_transfer"
+  }
+}
+
+

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 "firstEvent" as "oldest". 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.

+

In the event, we can also see the blockchainEvent itself, which has an output object. This contains the event payload that was set by the chaincode.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/custom_contracts/images/simple_storage_swagger.png b/v1.3.1/tutorials/custom_contracts/images/simple_storage_swagger.png new file mode 100644 index 000000000..1d49237f2 Binary files /dev/null and b/v1.3.1/tutorials/custom_contracts/images/simple_storage_swagger.png differ diff --git a/v1.3.1/tutorials/custom_contracts/images/tezos_contract_deployment.png b/v1.3.1/tutorials/custom_contracts/images/tezos_contract_deployment.png new file mode 100644 index 000000000..f2e29d4a2 Binary files /dev/null and b/v1.3.1/tutorials/custom_contracts/images/tezos_contract_deployment.png differ diff --git a/v1.3.1/tutorials/custom_contracts/images/tezos_contract_deployment2.png b/v1.3.1/tutorials/custom_contracts/images/tezos_contract_deployment2.png new file mode 100644 index 000000000..23dc9ac9f Binary files /dev/null and b/v1.3.1/tutorials/custom_contracts/images/tezos_contract_deployment2.png differ diff --git a/v1.3.1/tutorials/custom_contracts/images/tezos_contract_deployment3.png b/v1.3.1/tutorials/custom_contracts/images/tezos_contract_deployment3.png new file mode 100644 index 000000000..8b84d1794 Binary files /dev/null and b/v1.3.1/tutorials/custom_contracts/images/tezos_contract_deployment3.png differ diff --git a/v1.3.1/tutorials/custom_contracts/index.html b/v1.3.1/tutorials/custom_contracts/index.html new file mode 100644 index 000000000..7a7cfd049 --- /dev/null +++ b/v1.3.1/tutorials/custom_contracts/index.html @@ -0,0 +1,3463 @@ + + + + + + + + + + + + + + + + + + + + + + + Work with custom smart contracts - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Work with custom smart contracts

+ +

Quick reference

+

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.

+

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.

+

Key concepts

+

FireFly defines the following constructs to support custom smart contracts:

+
    +
  • Contract Interface: 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.
    • +
+

For more details, you can also have a look at the Reference page for the FireFly Interface Format.

+

For blockchains that offer a DSL describing the smart contract interface, such as Ethereum's ABI (Application Binary Interface), FireFly offers a convenience tool to convert the DSL into the FFI format.

+
+

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.

+
+
    +
  • HTTP API: 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 /invoke root path to submit transactions, and a /query root path to send query requests to read the state back out.
    • +
+

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 /invoke calls to eth_sendTransaction JSON-RPC requests, while /query calls are translated into eth_call JSON-RPC requests. One the other hand, the Fabric connector translates /invoke 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).

+
    +
  • Blockchain Event Listener: 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.
    • +
+

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.

+
    +
  • Event Subscription: While an event listener tells FireFly to keep track of certain events emitted by the blockchain, an event subscription tells FireFly to relay those events to the client application. Each subscriptions represents a stream of events that can be delivered to a listening client with various modes of delivery with at-least-once delivery guarantee.
    • +
+

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.

+

Custom onchain logic async programming in FireFly

+

Like the rest of FireFly, custom onchain logic support are implemented with an asynchronous programming model. The key concepts here are:

+
    +
  • Transactions are submitted to FireFly and an ID is returned. This is the Operation ID.
    • +
  • The transaction itself happens asynchronously from the HTTP request that initiated it
    • +
  • 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 blockchain_event_received when this happens.
    • +
+ + +

Smart Contracts Async Flow

+ + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/custom_contracts/pinning/index.html b/v1.3.1/tutorials/custom_contracts/pinning/index.html new file mode 100644 index 000000000..bb9b81568 --- /dev/null +++ b/v1.3.1/tutorials/custom_contracts/pinning/index.html @@ -0,0 +1,3676 @@ + + + + + + + + + + + + + + + + + + + + + + + Pinning Data - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Pin off-chain data to a custom blockchain transaction

+

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.

+
+

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.

+
+

Designing a compatible contract

+

In order to allow pinning a FireFly message batch with a custom contract transaction, your contract must +meet certain criteria.

+

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.

+

Second, this method must emit a BatchPin 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.

+

Ethereum

+
import "@hyperledger/firefly-contracts/contracts/IBatchPin.sol";
+
+contract CustomPin {
+    IBatchPin firefly;
+
+    function setFireFlyAddress(address addr) external {
+        firefly = IBatchPin(addr);
+    }
+
+    function sayHello(bytes calldata data) external {
+        require(
+            address(firefly) != address(0),
+            "CustomPin: FireFly address has not been set"
+        );
+
+        /* do custom things */
+
+        firefly.pinBatchData(data);
+    }
+}
+
+
    +
  • The method in question will receive packed "batch pin" data in its last method parameter (in the + form of ABI-encoded bytes). The method must invoke the pinBatchData 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.
    • +
  • 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 + /status API (under multiparty.contract.location 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.
    • +
+

Fabric

+
package chaincode
+
+import (
+    "encoding/json"
+    "fmt"
+
+    "github.com/hyperledger/fabric-contract-api-go/contractapi"
+    "github.com/hyperledger/firefly/custompin_sample/batchpin"
+)
+
+type SmartContract struct {
+    contractapi.Contract
+}
+
+func (s *SmartContract) MyCustomPin(ctx contractapi.TransactionContextInterface, data string) error {
+    event, err := batchpin.BuildEventFromString(ctx, data)
+    if err != nil {
+        return err
+    }
+    bytes, err := json.Marshal(event)
+    if err != nil {
+        return fmt.Errorf("failed to marshal event: %s", err)
+    }
+    return ctx.GetStub().SetEvent("BatchPin", bytes)
+}
+
+
    +
  • The method in question will received packed "batch pin" data in its last method parameter (in the + form of a JSON-encoded string). The method must unpack this argument into a JSON object.
    • +
  • The contract must directly set a BatchPin event in the same format that is used by the + FireFly Multiparty Contract.
    • +
+

Initializing FireFly

+

Once you have a contract designed, you can initialize your environment +using the blockchain of your choice.

+

No special initialization arguments are needed for Ethereum.

+

If you are using Fabric, you must pass the --custom-pin-support argument when initializing your +FireFly stack. This will ensure that the BatchPin 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.

+

Invoking the contract

+

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.

+

POST http://localhost:5000/api/v1/namespaces/default/apis/custom-pin/invoke/sayHello

+
{
+  "input": {},
+  "message": {
+    "data": [
+      {
+        "value": "payload here"
+      }
+    ]
+  }
+}
+
+

Listening for events

+

All parties that receive the message will receive a message_confirmed 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 message_confirmed +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.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/custom_contracts/tezos/index.html b/v1.3.1/tutorials/custom_contracts/tezos/index.html new file mode 100644 index 000000000..6a42abad1 --- /dev/null +++ b/v1.3.1/tutorials/custom_contracts/tezos/index.html @@ -0,0 +1,4787 @@ + + + + + + + + + + + + + + + + + + + + + + + Tezos - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Work with Tezos smart contracts

+

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.

+

Smart Contract Languages

+

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.

+
+

NOTE: For this tutorial we are going to use SmartPy for building Tezos smart contracts utilizing the broadly adopted Python language.

+
+

Example smart contract

+

First let's look at a simple contract smart contract called SimpleStorage, 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.

+
+

NOTE: Smart contract's tests (marked with @sp.add_test annotation) are used to verify the validity of contract entrypoints and do not affect the state of the contract during deployment.

+
+

Here is the source for this contract:

+
import smartpy as sp
+
+@sp.module
+def main():
+    # Declares a new contract
+    class SimpleStorage(sp.Contract):
+        # Storage. Persists in between transactions
+        def __init__(self, value):
+            self.data.x = value
+
+        # Allows the stored integer to be changed
+        @sp.entrypoint
+        def set(self, params):
+            self.data.x = params.value
+
+        # Returns the currently stored integer
+        @sp.onchain_view()
+        def get(self):
+            return self.data.x
+
+@sp.add_test()
+def test():
+    # Create a test scenario
+    scenario = sp.test_scenario("Test simple storage", main)
+    scenario.h1("SimpleStorage")
+
+    # Initialize the contract
+    c = main.SimpleStorage(12)
+
+    # Run some test cases
+    scenario += c
+    c.set(value=15)
+    scenario.verify(c.data.x == 15)
+    scenario.verify(scenario.compute(c.get()) == 15)
+
+

Contract deployment via SmartPy IDE

+

To deploy the contract, we will use SmartPy IDE.

+
    +
  1. Open an IDE;
    2. +
  2. Paste the contract code;
    3. +
  3. Click "Run code" button;
    4. +
  4. Then you will see "Show Michelson" button, click on that;
    5. +
  5. On the opened pop-up click button "Deploy Contract";
    6. +
  6. Choose the Ghostnet network;
    7. +
  7. Select an account, which you're going to use to deploy the contract;
    8. +
  8. Click "Estimate Cost From RPC" button;
    9. +
  9. Click "Deploy Contract" button;
    10. +
+

ContractDeployment +ContractDeployment2 +ContractDeployment3

+

Here we can see that our new contract address is KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg. This is the address that we will reference in the rest of this guide.

+

Contract deployment via HTTP API

+

To deploy the contract we can use HTTP API: +POST http://localhost:5000/api/v1/namespaces/default/contracts/deploy

+
{
+  "contract": {
+    "code": [
+      {
+        "prim": "storage",
+        "args": [
+          {
+            "prim": "int"
+          }
+        ]
+      },
+      {
+        "prim": "parameter",
+        "args": [
+          {
+            "prim": "int",
+            "annots": ["%set"]
+          }
+        ]
+      },
+      {
+        "prim": "code",
+        "args": [
+          [
+            {
+              "prim": "CAR"
+            },
+            {
+              "prim": "NIL",
+              "args": [
+                {
+                  "prim": "operation"
+                }
+              ]
+            },
+            {
+              "prim": "PAIR"
+            }
+          ]
+        ]
+      },
+      {
+        "prim": "view",
+        "args": [
+          {
+            "string": "get"
+          },
+          {
+            "prim": "unit"
+          },
+          {
+            "prim": "int"
+          },
+          [
+            {
+              "prim": "CDR"
+            }
+          ]
+        ]
+      }
+    ],
+    "storage": {
+      "int": "12"
+    }
+  }
+}
+
+

The contract field has two fields - code with Michelson code of contract and storage with initial Storage values.

+

The response of request above:

+
{
+  "id": "0c3810c7-baed-4077-9d2c-af316a4a567f",
+  "namespace": "default",
+  "tx": "21d03e6d-d106-48f4-aacd-688bf17b71fd",
+  "type": "blockchain_deploy",
+  "status": "Pending",
+  "plugin": "tezos",
+  "input": {
+    "contract": {
+      "code": [
+        {
+          "args": [
+            {
+              "prim": "int"
+            }
+          ],
+          "prim": "storage"
+        },
+        {
+          "args": [
+            {
+              "annots": ["%set"],
+              "prim": "int"
+            }
+          ],
+          "prim": "parameter"
+        },
+        {
+          "args": [
+            [
+              {
+                "prim": "CAR"
+              },
+              {
+                "args": [
+                  {
+                    "prim": "operation"
+                  }
+                ],
+                "prim": "NIL"
+              },
+              {
+                "prim": "PAIR"
+              }
+            ]
+          ],
+          "prim": "code"
+        },
+        {
+          "args": [
+            {
+              "string": "get"
+            },
+            {
+              "prim": "unit"
+            },
+            {
+              "prim": "int"
+            },
+            [
+              {
+                "prim": "CDR"
+              }
+            ]
+          ],
+          "prim": "view"
+        }
+      ],
+      "storage": {
+        "int": "12"
+      }
+    },
+    "definition": null,
+    "input": null,
+    "key": "tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31",
+    "options": null
+  },
+  "created": "2024-04-01T14:20:20.665039Z",
+  "updated": "2024-04-01T14:20:20.665039Z"
+}
+
+

The success result of deploy can be checked by +GET http://localhost:5000/api/v1/namespaces/default/operations/0c3810c7-baed-4077-9d2c-af316a4a567f +where 0c3810c7-baed-4077-9d2c-af316a4a567f is operation id from response above.

+

The success response:

+
{
+  "id": "0c3810c7-baed-4077-9d2c-af316a4a567f",
+  "namespace": "default",
+  "tx": "21d03e6d-d106-48f4-aacd-688bf17b71fd",
+  "type": "blockchain_deploy",
+  "status": "Succeeded",
+  "plugin": "tezos",
+  "input": {
+    "contract": {
+      "code": [
+        {
+          "args": [
+            {
+              "prim": "int"
+            }
+          ],
+          "prim": "storage"
+        },
+        {
+          "args": [
+            {
+              "annots": ["%set"],
+              "prim": "int"
+            }
+          ],
+          "prim": "parameter"
+        },
+        {
+          "args": [
+            [
+              {
+                "prim": "CAR"
+              },
+              {
+                "args": [
+                  {
+                    "prim": "operation"
+                  }
+                ],
+                "prim": "NIL"
+              },
+              {
+                "prim": "PAIR"
+              }
+            ]
+          ],
+          "prim": "code"
+        },
+        {
+          "args": [
+            {
+              "string": "get"
+            },
+            {
+              "prim": "unit"
+            },
+            {
+              "prim": "int"
+            },
+            [
+              {
+                "prim": "CDR"
+              }
+            ]
+          ],
+          "prim": "view"
+        }
+      ],
+      "storage": {
+        "int": "12"
+      }
+    },
+    "definition": null,
+    "input": null,
+    "key": "tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31",
+    "options": null
+  },
+  "output": {
+    "headers": {
+      "requestId": "default:0c3810c7-baed-4077-9d2c-af316a4a567f",
+      "type": "TransactionSuccess"
+    },
+    "protocolId": "ProxfordYmVfjWnRcgjWH36fW6PArwqykTFzotUxRs6gmTcZDuH",
+    "transactionHash": "ootDut4xxR2yeYz6JuySuyTVZnXgda2t8SYrk3iuJpm531TZuCj"
+  },
+  "created": "2024-04-01T14:20:20.665039Z",
+  "updated": "2024-04-01T14:20:20.665039Z",
+  "detail": {
+    "created": "2024-04-01T14:20:21.928976Z",
+    "firstSubmit": "2024-04-01T14:20:22.714493Z",
+    "from": "tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31",
+    "gasPrice": "0",
+    "historySummary": [
+      {
+        "count": 1,
+        "firstOccurrence": "2024-04-01T14:20:21.930764Z",
+        "lastOccurrence": "2024-04-01T14:20:21.930765Z",
+        "subStatus": "Received"
+      },
+      {
+        "action": "AssignNonce",
+        "count": 2,
+        "firstOccurrence": "2024-04-01T14:20:21.930767Z",
+        "lastOccurrence": "2024-04-01T14:20:22.714772Z"
+      },
+      {
+        "action": "RetrieveGasPrice",
+        "count": 1,
+        "firstOccurrence": "2024-04-01T14:20:22.714774Z",
+        "lastOccurrence": "2024-04-01T14:20:22.714774Z"
+      },
+      {
+        "action": "SubmitTransaction",
+        "count": 1,
+        "firstOccurrence": "2024-04-01T14:20:22.715269Z",
+        "lastOccurrence": "2024-04-01T14:20:22.715269Z"
+      },
+      {
+        "action": "ReceiveReceipt",
+        "count": 1,
+        "firstOccurrence": "2024-04-01T14:20:29.244396Z",
+        "lastOccurrence": "2024-04-01T14:20:29.244396Z"
+      },
+      {
+        "action": "Confirm",
+        "count": 1,
+        "firstOccurrence": "2024-04-01T14:20:29.244762Z",
+        "lastOccurrence": "2024-04-01T14:20:29.244762Z"
+      }
+    ],
+    "id": "default:0c3810c7-baed-4077-9d2c-af316a4a567f",
+    "lastSubmit": "2024-04-01T14:20:22.714493Z",
+    "nonce": "23094946",
+    "policyInfo": {},
+    "receipt": {
+      "blockHash": "BLvWL4t8GbaufGcQwiv3hHCsvgD6qwXfAXofyvojSMoFeGMXMR1",
+      "blockNumber": "5868268",
+      "contractLocation": {
+        "address": "KT1CkTPsgTUQxR3CCpvtrcuQFV5Jf7cJgHFg"
+      },
+      "extraInfo": [
+        {
+          "consumedGas": "584",
+          "contractAddress": "KT1CkTPsgTUQxR3CCpvtrcuQFV5Jf7cJgHFg",
+          "counter": null,
+          "errorMessage": null,
+          "fee": null,
+          "from": null,
+          "gasLimit": null,
+          "paidStorageSizeDiff": "75",
+          "status": "applied",
+          "storage": null,
+          "storageLimit": null,
+          "storageSize": "75",
+          "to": null
+        }
+      ],
+      "protocolId": "ProxfordYmVfjWnRcgjWH36fW6PArwqykTFzotUxRs6gmTcZDuH",
+      "success": true,
+      "transactionIndex": "0"
+    },
+    "sequenceId": "018e9a08-582a-01ec-9209-9d79ef742c9b",
+    "status": "Succeeded",
+    "transactionData": "c37274b662d68da8fdae2a02ad6c460a79933c70c6fa7500dc98a9ade6822f026d00673bb6e6298063f97940953de23d441ab20bf757f602a3cd810bad05b003000000000041020000003c0500045b00000004257365740501035b050202000000080316053d036d03420991000000130100000003676574036c035b020000000203170000000000000002000c",
+    "transactionHash": "ootDut4xxR2yeYz6JuySuyTVZnXgda2t8SYrk3iuJpm531TZuCj",
+    "transactionHeaders": {
+      "from": "tz1V3spuktTP2wuEZP7D2hJruLZ5uJTuJk31",
+      "nonce": "23094946"
+    },
+    "updated": "2024-04-01T14:20:29.245172Z"
+  }
+}
+
+

The FireFly Interface Format

+

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.

+

Schema details

+

The details field is used to encapsulate blockchain specific type information about a specific field. (More details at schema details)

+

Supported Tezos types

+
    +
  • nat
    • +
  • integer
    • +
  • string
    • +
  • address
    • +
  • bytes
    • +
  • boolean
    • +
  • variant
    • +
  • list
    • +
  • struct
    • +
  • map
    • +
+

Internal type vs Internal schema

+

internalType is a field which is used to describe tezos primitive types

+
{
+  "details": {
+    "type": "address",
+    "internalType": "address"
+  }
+}
+
+

internalSchema in turn is used to describe more complex tezos types as list, struct or variant

+

Struct example:

+
{
+  "details": {
+    "type": "schema",
+    "internalSchema": {
+      "type": "struct",
+      "args": [
+        {
+          "name": "metadata",
+          "type": "bytes"
+        },
+        {
+          "name": "token_id",
+          "type": "nat"
+        }
+      ]
+    }
+  }
+}
+
+

List example:

+
{
+  "details": {
+    "type": "schema",
+    "internalSchema": {
+      "type": "struct",
+      "args": [
+        {
+          "name": "metadata",
+          "type": "bytes"
+        },
+        {
+          "name": "token_id",
+          "type": "nat"
+        }
+      ]
+    }
+  }
+}
+
+

Variant example:

+
{
+  "details": {
+    "type": "schema",
+    "internalSchema": {
+      "type": "variant",
+      "variants": ["add_operator", "remove_operator"],
+      "args": [
+        {
+          "type": "struct",
+          "args": [
+            {
+              "name": "owner",
+              "type": "address"
+            },
+            {
+              "name": "operator",
+              "type": "address"
+            },
+            {
+              "name": "token_id",
+              "type": "nat"
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+
+

Map example:

+
{
+  "details": {
+    "type": "schema",
+    "internalSchema": {
+      "type": "map",
+      "args": [
+        {
+          "name": "key",
+          "type": "integer"
+        },
+        {
+          "name": "value",
+          "type": "string"
+        }
+      ]
+    }
+  }
+}
+
+

Options

+

Option type is used to indicate a value as optional (see more at smartpy options)

+
{
+  "details": {
+    "type": "string",
+    "internalType": "string",
+    "kind": "option"
+  }
+}
+
+

FA2 example

+

The following FFI sample demonstrates the specification for the widely used FA2 (analogue of ERC721 for EVM) smart contract:

+
{
+  "namespace": "default",
+  "name": "fa2",
+  "version": "v1.0.0",
+  "description": "",
+  "methods": [
+    {
+      "name": "burn",
+      "pathname": "",
+      "description": "",
+      "params": [
+        {
+          "name": "token_ids",
+          "schema": {
+            "type": "array",
+            "details": {
+              "type": "nat",
+              "internalType": "nat"
+            }
+          }
+        }
+      ],
+      "returns": []
+    },
+    {
+      "name": "destroy",
+      "pathname": "",
+      "description": "",
+      "params": [],
+      "returns": []
+    },
+    {
+      "name": "mint",
+      "pathname": "",
+      "description": "",
+      "params": [
+        {
+          "name": "owner",
+          "schema": {
+            "type": "string",
+            "details": {
+              "type": "address",
+              "internalType": "address"
+            }
+          }
+        },
+        {
+          "name": "requests",
+          "schema": {
+            "type": "array",
+            "details": {
+              "type": "schema",
+              "internalSchema": {
+                "type": "struct",
+                "args": [
+                  {
+                    "name": "metadata",
+                    "type": "bytes"
+                  },
+                  {
+                    "name": "token_id",
+                    "type": "nat"
+                  }
+                ]
+              }
+            }
+          }
+        }
+      ],
+      "returns": []
+    },
+    {
+      "name": "pause",
+      "pathname": "",
+      "description": "",
+      "params": [
+        {
+          "name": "pause",
+          "schema": {
+            "type": "boolean",
+            "details": {
+              "type": "boolean",
+              "internalType": "boolean"
+            }
+          }
+        }
+      ],
+      "returns": []
+    },
+    {
+      "name": "select",
+      "pathname": "",
+      "description": "",
+      "params": [
+        {
+          "name": "batch",
+          "schema": {
+            "type": "array",
+            "details": {
+              "type": "schema",
+              "internalSchema": {
+                "type": "struct",
+                "args": [
+                  {
+                    "name": "token_id",
+                    "type": "nat"
+                  },
+                  {
+                    "name": "recipient",
+                    "type": "address"
+                  },
+                  {
+                    "name": "token_id_start",
+                    "type": "nat"
+                  },
+                  {
+                    "name": "token_id_end",
+                    "type": "nat"
+                  }
+                ]
+              }
+            }
+          }
+        }
+      ],
+      "returns": []
+    },
+    {
+      "name": "transfer",
+      "pathname": "",
+      "description": "",
+      "params": [
+        {
+          "name": "batch",
+          "schema": {
+            "type": "array",
+            "details": {
+              "type": "schema",
+              "internalSchema": {
+                "type": "struct",
+                "args": [
+                  {
+                    "name": "from_",
+                    "type": "address"
+                  },
+                  {
+                    "name": "txs",
+                    "type": "list",
+                    "args": [
+                      {
+                        "type": "struct",
+                        "args": [
+                          {
+                            "name": "to_",
+                            "type": "address"
+                          },
+                          {
+                            "name": "token_id",
+                            "type": "nat"
+                          },
+                          {
+                            "name": "amount",
+                            "type": "nat"
+                          }
+                        ]
+                      }
+                    ]
+                  }
+                ]
+              }
+            }
+          }
+        }
+      ],
+      "returns": []
+    },
+    {
+      "name": "update_admin",
+      "pathname": "",
+      "description": "",
+      "params": [
+        {
+          "name": "admin",
+          "schema": {
+            "type": "string",
+            "details": {
+              "type": "address",
+              "internalType": "address"
+            }
+          }
+        }
+      ],
+      "returns": []
+    },
+    {
+      "name": "update_operators",
+      "pathname": "",
+      "description": "",
+      "params": [
+        {
+          "name": "requests",
+          "schema": {
+            "type": "array",
+            "details": {
+              "type": "schema",
+              "internalSchema": {
+                "type": "variant",
+                "variants": ["add_operator", "remove_operator"],
+                "args": [
+                  {
+                    "type": "struct",
+                    "args": [
+                      {
+                        "name": "owner",
+                        "type": "address"
+                      },
+                      {
+                        "name": "operator",
+                        "type": "address"
+                      },
+                      {
+                        "name": "token_id",
+                        "type": "nat"
+                      }
+                    ]
+                  }
+                ]
+              }
+            }
+          }
+        }
+      ],
+      "returns": []
+    }
+  ],
+  "events": []
+}
+
+

Broadcast the contract interface

+

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.

+

We will use the FFI JSON constructed above and POST that to the /contracts/interfaces API endpoint.

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/contracts/interfaces

+
{
+  "namespace": "default",
+  "name": "simplestorage",
+  "version": "v1.0.0",
+  "description": "",
+  "methods": [
+    {
+      "name": "set",
+      "pathname": "",
+      "description": "",
+      "params": [
+        {
+          "name": "newValue",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "integer",
+              "internalType": "integer"
+            }
+          }
+        }
+      ],
+      "returns": []
+    },
+    {
+      "name": "get",
+      "pathname": "",
+      "description": "",
+      "params": [],
+      "returns": []
+    }
+  ],
+  "events": []
+}
+
+

Response

+
{
+  "id": "f9e34787-e634-46cd-af47-b52c537404ff",
+  "namespace": "default",
+  "name": "simplestorage",
+  "description": "",
+  "version": "v1.0.0",
+  "methods": [
+    {
+      "id": "78f13a7f-7b85-47c3-bf51-346a9858c027",
+      "interface": "f9e34787-e634-46cd-af47-b52c537404ff",
+      "name": "set",
+      "namespace": "default",
+      "pathname": "set",
+      "description": "",
+      "params": [
+        {
+          "name": "newValue",
+          "schema": {
+            "type": "integer",
+            "details": {
+              "type": "integer",
+              "internalType": "integer"
+            }
+          }
+        }
+      ],
+      "returns": []
+    },
+    {
+      "id": "ee864e25-c3f7-42d3-aefd-a82f753e9002",
+      "interface": "f9e34787-e634-46cd-af47-b52c537404ff",
+      "name": "get",
+      "namespace": "tezos",
+      "pathname": "get",
+      "description": "",
+      "params": [],
+      "returns": []
+    }
+  ]
+}
+
+
+

NOTE: We can broadcast this contract interface conveniently with the help of FireFly Sandbox running at http://127.0.0.1:5108

+
+
    +
  • Go to the Contracts Section
    • +
  • Click on Define a Contract Interface
    • +
  • Select FFI - FireFly Interface in the Interface Fromat dropdown
    • +
  • Copy the FFI JSON crafted by you into the Schema Field
    • +
  • Click on Run
    • +
+

Create an HTTP API for the contract

+

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.

+

We need to copy the id field we got in the response from the previous step to the interface.id 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 simple-storage. Lastly, in the location.address field, we're telling FireFly where an instance of the contract is deployed on-chain.

+
+

NOTE: The location 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.

+
+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/apis

+
{
+  "name": "simple-storage",
+  "interface": {
+    "id": "f9e34787-e634-46cd-af47-b52c537404ff"
+  },
+  "location": {
+    "address": "KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg"
+  }
+}
+
+

Response

+
{
+  "id": "af09de97-741d-4f61-8d30-4db5e7460f76",
+  "namespace": "default",
+  "interface": {
+    "id": "f9e34787-e634-46cd-af47-b52c537404ff"
+  },
+  "location": {
+    "address": "KT1ED4gj2xZnp8318yxa5NpvyvW15pqe4yFg"
+  },
+  "name": "simple-storage",
+  "urls": {
+    "openapi": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api/swagger.json",
+    "ui": "http://127.0.0.1:5000/api/v1/namespaces/default/apis/simple-storage/api"
+  }
+}
+
+

View OpenAPI spec for the contract

+

You'll notice in the response body that there are a couple of URLs near the bottom. If you navigate to the one labeled ui in your browser, you should see the Swagger UI for your smart contract.

+

Swagger UI

+

Invoke the smart contract

+

Now that we've got everything set up, it's time to use our smart contract! We're going to make a POST request to the invoke/set endpoint to set the integer value on-chain. Let's set it to the value of 3 right now.

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/invoke/set

+
{
+  "input": {
+    "newValue": 3
+  }
+}
+
+

Response

+
{
+  "id": "87c7ee1b-33d1-46e2-b3f5-8566c14367cf",
+  "type": "blockchain_invoke",
+  "status": "Pending",
+  "..."
+}
+
+

You'll notice that we got an ID back with status Pending, 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.

+

Query the current value

+

To make a read-only request to the blockchain to check the current value of the stored integer, we can make a POST to the query/get endpoint.

+

Request

+

POST http://localhost:5000/api/v1/namespaces/default/apis/simple-storage/query/get

+
{}
+
+

Response

+
{
+  "3"
+}
+
+
+

NOTE: Some contracts may have queries that require input parameters. That's why the query endpoint is a POST, rather than a GET 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.

+
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/define_datatype/index.html b/v1.3.1/tutorials/define_datatype/index.html new file mode 100644 index 000000000..9d6565df4 --- /dev/null +++ b/v1.3.1/tutorials/define_datatype/index.html @@ -0,0 +1,3738 @@ + + + + + + + + + + + + + + + + + + + + + + + Define a datatype - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Define a datatype

+

Quick reference

+

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.

+

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.

+

Additional info

+ +

Example 1: Broadcast new datatype

+

POST /api/v1/namespaces/{ns}/datatypes

+
{
+  "name": "widget",
+  "version": "0.0.2",
+  "value": {
+    "$id": "https://example.com/widget.schema.json",
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "Widget",
+    "type": "object",
+    "properties": {
+      "id": {
+        "type": "string",
+        "description": "The unique identifier for the widget."
+      },
+      "name": {
+        "type": "string",
+        "description": "The person's last name."
+      }
+    }
+  }
+}
+
+

Example message response

+

Status: 202 Accepted - a broadcast message has been sent, and on confirmation the new +datatype will be created (unless it conflicts with another definition with the same +name and version that was ordered onto the blockchain before this definition).

+
{
+  "header": {
+    "id": "727f7d3a-d07e-4e80-95af-59f8d2ac7531", // this is the ID of the message, not the data type
+    "type": "definition", // a special type for system broadcasts
+    "txtype": "batch_pin", // the broadcast is pinned to the chain
+    "author": "0x0a65365587a65ce44938eab5a765fe8bc6532bdf", // the local identity
+    "created": "2021-07-01T21:06:26.9997478Z", // the time the broadcast was sent
+    "namespace": "ff_system", // the data/message broadcast happens on the system namespace
+    "topic": [
+      "ff_ns_default" // the namespace itself is used in the topic
+    ],
+    "tag": "ff_define_datatype", // a tag instructing FireFly to process this as a datatype definition
+    "datahash": "56bd677e3e070ba62f547237edd7a90df5deaaf1a42e7d6435ec66a587c14370"
+  },
+  "hash": "5b6593720243831ba9e4ad002c550e95c63704b2c9dbdf31135d7d9207f8cae8",
+  "state": "ready", // this message is stored locally but not yet confirmed
+  "data": [
+    {
+      "id": "7539a0ab-78d8-4d42-b283-7e316b3afed3", // this data object in the ff_system namespace, contains the schema
+      "hash": "22ba1cdf84f2a4aaffac665c83ff27c5431c0004dc72a9bf031ae35a75ac5aef"
+    }
+  ]
+}
+
+

Lookup the confirmed data type

+

GET /api/v1/namespaces/default/datatypes?name=widget&version=0.0.2

+
[
+  {
+    "id": "421c94b1-66ce-4ba0-9794-7e03c63df29d", // an ID allocated to the datatype
+    "message": "727f7d3a-d07e-4e80-95af-59f8d2ac7531", // the message that broadcast this data type
+    "validator": "json", // the type of validator that this datatype can be used for (this one is JSON Schema)
+    "namespace": "default", // the namespace of the datatype
+    "name": "widget", // the name of the datatype
+    "version": "0.0.2", // the version of the data type
+    "hash": "a4dceb79a21937ca5ea9fa22419011ca937b4b8bc563d690cea3114af9abce2c", // hash of the schema itself
+    "created": "2021-07-01T21:06:26.983986Z", // time it was confirmed
+    "value": {
+      // the JSON schema itself
+      "$id": "https://example.com/widget.schema.json",
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "title": "Widget",
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "The unique identifier for the widget."
+        },
+        "name": {
+          "type": "string",
+          "description": "The person's last name."
+        }
+      }
+    }
+  }
+]
+
+

Example private send referring to the datatype

+

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 message_rejected event +(rather than message_confirmed) for any message that arrives referring to that data.

+

POST /api/v1/namespaces/default/send/message

+
{
+  "header": {
+    "tag": "new_widget_created",
+    "topic": ["widget_id_12345"]
+  },
+  "group": {
+    "members": [
+      {
+        "identity": "org_1"
+      }
+    ]
+  },
+  "data": [
+    {
+      "datatype": {
+        "name": "widget",
+        "version": "0.0.2"
+      },
+      "value": {
+        "id": "widget_id_12345",
+        "name": "superwidget"
+      }
+    }
+  ]
+}
+
+

Defining Datatypes using the Sandbox

+

You can also define a datatype through the FireFly Sandbox.

+

To get started, open up the Web UI and Sanbox UI for at least one of your members. The URLs for these were printed in your terminal when you started your FireFly stack.

+

In the sandbox, enter the datatype's name, version, and JSON Schema as seen in the screenshot below.

+
{
+  "name": "widget",
+  "version": "0.0.2",
+  "value": {
+    "$id": "https://example.com/widget.schema.json",
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "Widget",
+    "type": "object",
+    "properties": {
+      "id": {
+        "type": "string",
+        "description": "The unique identifier for the widget."
+      },
+      "name": {
+        "type": "string",
+        "description": "The person's last name."
+      }
+    }
+  }
+}
+
+

Defining a Datatype

+

Notice how the data field in the center panel updates in real time.

+

Click the blue Run button. This should return a 202 response immediately in the Server Response section and will populate the right hand panel with transaction information after a few seconds.

+

Message Broadcast

+

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

+

Successful Transaction

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/events/index.html b/v1.3.1/tutorials/events/index.html new file mode 100644 index 000000000..a7f3614b3 --- /dev/null +++ b/v1.3.1/tutorials/events/index.html @@ -0,0 +1,3766 @@ + + + + + + + + + + + + + + + + + + + + + + + Listen for events - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Listen for events

+

Quick reference

+

Probably the most important aspect of FireFly is that it is an event-driven programming model.

+

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.

+

This allows orchestration of complex multi-party system applications and business processes.

+

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.

+

The event transports are pluggable. The core transports are WebSockets and Webhooks. +We focus on WebSockets in this getting started guide.

+
+

Check out the Request/Reply section for more information on Webhooks

+
+

Additional info

+ +

WebSockets Example 1: Ephemeral subscription with auto-commit

+

The simplest way to get started consuming events, is with an ephemeral WebSocket listener.

+

Example connection URL:

+

ws://localhost:5000/ws?namespace=default&ephemeral&autoack&filter.events=message_confirmed

+
    +
  • namespace=default - event listeners are scoped to a namespace
    • +
  • ephemeral - listen for events that occur while this connection is active, but do not remember the app instance (great for UIs)
    • +
  • autoack- automatically acknowledge each event, so the next event is sent (great for UIs)
    • +
  • filter.events=message_confirmed - only listen for events resulting from a message confirmation
    • +
+

There are a number of browser extensions that let you experiment with WebSockets:

+

Browser Extension

+

Example event payload

+

The events (by default) do not contain the payload data, just the event and referred message. +This means the WebSocket payloads are a predictably small size, and the application can +use the information in the message to post-filter the event to decide if it needs to download +the full data.

+
+

There are server-side filters provided on events as well

+
+
{
+  "id": "8f0da4d7-8af7-48da-912d-187979bf60ed",
+  "sequence": 61,
+  "type": "message_confirmed",
+  "namespace": "default",
+  "reference": "9710a350-0ba1-43c6-90fc-352131ce818a",
+  "created": "2021-07-02T04:37:47.6556589Z",
+  "subscription": {
+    "id": "2426c5b1-ffa9-4f7d-affb-e4e541945808",
+    "namespace": "default",
+    "name": "2426c5b1-ffa9-4f7d-affb-e4e541945808"
+  },
+  "message": {
+    "header": {
+      "id": "9710a350-0ba1-43c6-90fc-352131ce818a",
+      "type": "broadcast",
+      "txtype": "batch_pin",
+      "author": "0x1d14b65d2dd5c13f6cb6d3dc4aa13c795a8f3b28",
+      "created": "2021-07-02T04:37:40.1257944Z",
+      "namespace": "default",
+      "topic": ["default"],
+      "datahash": "cd6a09a15ccd3e6ed1d67d69fa4773b563f27f17f3eaad611a2792ba945ca34f"
+    },
+    "hash": "1b6808d2b95b418e54e7bd34593bfa36a002b841ac42f89d00586dac61e8df43",
+    "batchID": "16ffc02c-8cb0-4e2f-8b58-a707ad1d1eae",
+    "state": "confirmed",
+    "confirmed": "2021-07-02T04:37:47.6548399Z",
+    "data": [
+      {
+        "id": "b3a814cc-17d1-45d5-975e-90279ed2c3fc",
+        "hash": "9ddefe4435b21d901439e546d54a14a175a3493b9fd8fbf38d9ea6d3cbf70826"
+      }
+    ]
+  }
+}
+
+

Download the message and data

+

A simple REST API is provided to allow you to download the data associated with the message:

+

GET /api/v1/namespaces/default/messages/{id}?data=true

+

Download just the data array associated with a message

+

As you already have the message object in the event delivery, you can query just the array +of data objects as follows:

+

GET /api/v1/namespaces/default/messages/{id}/data

+

WebSockets Example 2: Durable subscription for your application, with manual-commit

+

To reliably process messages within your application, you should first set up a subscription.

+

A subscription requests that:

+
    +
  • FireFly keeps a record of the latest event consumed by that application
    • +
  • FireFly only delivers one copy of the event to the application, even when there are multiple active connections
    • +
+

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 id comes from the event +it received):

+
{ "type": "ack", "id": "617db63-2cf5-4fa3-8320-46150cbb5372" }
+
+
+

You must send an acknowledgement for every message, or you will stop receiving messages.

+
+

Set up the WebSocket subscription

+

Each subscription is scoped to a namespace, and must have a name. You can then choose to perform +server-side filtering on the events using regular expressions matched against the information +in the event.

+

POST /namespaces/default/subscriptions

+
{
+  "transport": "websockets",
+  "name": "app1",
+  "filter": {
+    "blockchainevent": {
+      "listener": ".*",
+      "name": ".*"
+    },
+    "events": ".*",
+    "message": {
+      "author": ".*",
+      "group": ".*",
+      "tag": ".*",
+      "topics": ".*"
+    },
+    "transaction": {
+      "type": ".*"
+    }
+  },
+  "options": {
+    "firstEvent": "newest",
+    "readAhead": 50
+  }
+}
+
+

Connect to consume messages

+

Example connection URL:

+

ws://localhost:5000/ws?namespace=default&name=app1

+
    +
  • namespace=default - event listeners are scoped to a namespace
    • +
  • name=app1 - the subscription name
    • +
+

Custom Contract Events

+

If you are interested in learning more about events for custom smart contracts, please see the Working with custom smart contracts section.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/private_send/index.html b/v1.3.1/tutorials/private_send/index.html new file mode 100644 index 000000000..a9c70c9dd --- /dev/null +++ b/v1.3.1/tutorials/private_send/index.html @@ -0,0 +1,3911 @@ + + + + + + + + + + + + + + + + + + + + + + + Privately send data - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Privately send data

+

Quick reference

+
    +
  • Sends a message to a restricted set of parties
    • +
  • The message describes who sent it, to whom, and exactly what data was sent
    • +
  • A message has one or more attached pieces of business data
    • +
  • Can be sent in-line, uploaded in advanced, or received from other parties
    • +
  • Can include smaller JSON payloads suitable for database storage
      +
    • These can be verified against a datatype
      • +
    +
    • +
  • Can include references to large (multi megabyte/gigabyte) Blob data
    • +
  • A group specifies who has visibility to the data
    • +
  • The author must be included in the group - auto-added if omitted
    • +
  • Can be specified in-line in the message by listing recipients directly
    • +
  • Can be referred to by hash
    • +
  • Private sends are optionally sequenced via pinning to the blockchain
    • +
  • If the send is pinned:
      +
    • The blockchain does not contain any data, just a hash pin
      • +
    • Even the ordering context (topic) is obscured in the on-chain data
      • +
    • This is true regardless of whether a restricted set of participants + are maintaining the ledger, such as in the case of a Fabric Channel.
      • +
    • The message should not be considered confirmed (even by the sender) until it + has been sequenced via the blockchain and a message_confirmed event occurs
      • +
    • Batched for efficiency
      • +
    • One batch can pin hundreds of private message sends
      • +
    • The batch flows privately off-chain from the sender to each recipient
      • +
    +
    • +
  • If the send is unpinned:
      +
    • No data is written to the blockchain at all
      • +
    • The message is marked confirmed immediately
      • +
    • The sender receives a message_confirmed event immediately
      • +
    • The other parties in the group get message_confirmed events as soon as the data arrives
      • +
    +
    • +
+

Additional info

+ +

Example 1: Pinned private send of in-line string data

+

POST /api/v1/namespaces/default/messages/private

+
{
+  "data": [
+    {
+      "value": "a string"
+    }
+  ],
+  "group": {
+    "members": [
+      {
+        "identity": "org_1"
+      }
+    ]
+  }
+}
+
+

Example message response

+

Status: 202 Accepted - the message is on it's way, but has not yet been confirmed.

+
{
+  "header": {
+    "id": "c387e9d2-bdac-44cc-9dd5-5e7f0b6b0e58", // uniquely identifies this private message
+    "type": "private", // set automatically
+    "txtype": "batch_pin", // message will be batched, and sequenced via the blockchain
+    "author": "0x0a65365587a65ce44938eab5a765fe8bc6532bdf", // set automatically in this example to the node org
+    "created": "2021-07-02T02:37:13.4642085Z", // set automatically
+    "namespace": "default", // the 'default' namespace was set in the URL
+    // The group hash is calculated from the resolved list of group participants.
+    // The first time a group is used, the participant list is sent privately along with the
+    // batch of messages in a `groupinit` message.
+    "group": "2aa5297b5eed0c3a612a667c727ca38b54fb3b5cc245ebac4c2c7abe490bdf6c",
+    "topics": [
+      "default" // the default topic that the message is published on, if no topic is set
+    ],
+    // datahash is calculated from the data array below
+    "datahash": "24b2d583b87eda952fa00e02c6de4f78110df63218eddf568f0240be3d02c866"
+  },
+  "hash": "423ad7d99fd30ff679270ad2b6b35cdd85d48db30bafb71464ca1527ce114a60", // hash of the header
+  "state": "ready", // this message is stored locally but not yet confirmed
+  "data": [
+    // one item of data was stored
+    {
+      "id": "8d8635e2-7c90-4963-99cc-794c98a68b1d", // can be used to query the data in the future
+      "hash": "c95d6352f524a770a787c16509237baf7eb59967699fb9a6d825270e7ec0eacf" // sha256 hash of `"a string"`
+    }
+  ]
+}
+
+

Example 2: Unpinned private send of in-line string data

+

Set header.txtype: "none" to disable pinning of the private message send to the blockchain. +The message is sent immediately (no batching) over the private data exchange.

+

POST /api/v1/namespaces/default/messages/private

+
{
+  "header": {
+    "txtype": "none"
+  },
+  "data": [
+    {
+      "value": "a string"
+    }
+  ],
+  "group": {
+    "members": [
+      {
+        "identity": "org_1"
+      }
+    ]
+  }
+}
+
+

Example 3: Inline object data to a topic (no datatype verification)

+

It is very good practice to set a tag and topic in each of your messages:

+
    +
  • tag 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.
    • +
  • topic 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.
    • +
+

POST /api/v1/namespaces/default/messages/private

+
{
+  "header": {
+    "tag": "new_widget_created",
+    "topics": ["widget_id_12345"]
+  },
+  "group": {
+    "members": [
+      {
+        "identity": "org_1"
+      }
+    ]
+  },
+  "data": [
+    {
+      "value": {
+        "id": "widget_id_12345",
+        "name": "superwidget"
+      }
+    }
+  ]
+}
+
+

Notes on why setting a topic is important

+

The FireFly aggregator uses the topic (obfuscated on chain) to determine if a +message is the next message in an in-flight sequence for any groups the node is +involved in. If it is, then that message must receive all off-chain private data +and be confirmed before any subsequent messages can be confirmed on the same sequence.

+

So if you use the same topic in every message, then a single failed send on one +topic blocks delivery of all messages between those parties, until the missing +data arrives.

+

Instead it is best practice to set the topic on your messages to value +that identifies an ordered stream of business processing. Some examples:

+
    +
  • A long-running business process instance identifier assigned at initiation
    • +
  • A real-world business transaction identifier used off-chain
    • +
  • The agreed identifier of an asset you are attaching a stream of evidence to
    • +
  • An NFT identifier that is assigned to an asset (digital twin scenarios)
    • +
  • An agreed primary key for a data resource being reconciled between multiple parties
    • +
+

The topic field is an array, because there are cases (such as merging two identifiers) +where you need a message to be deterministically ordered across multiple sequences. +However, this is an advanced use case and you are likely to set a single topic +on the vast majority of your messages.

+

Example 3: Upload a blob with metadata and send privately

+

Here we make two API calls.

+
    +
  1. +

    Create the data object explicitly, using a multi-part form upload

    +
    2. +
  2. +

    You can also just post JSON to this endpoint

    +
    3. +
  3. +

    Privately send a message referring to that data

    +
    4. +
  4. +

    The Blob is sent privately to each party

    +
    5. +
  5. A pin goes to the blockchain
    6. +
  6. The metadata goes into a batch with the message
    7. +
+

Multipart form post of a file

+

Example curl command (Linux/Mac) to grab an image from the internet, +and pipe it into a multi-part form post to FireFly.

+
+

Note we use autometa to cause FireFly to automatically add +the filename, and size, to the JSON part of the data object for us.

+
+
curl -sLo - https://github.com/hyperledger/firefly/raw/main/docs/firefly_logo.png \
+ | curl --form autometa=true --form file=@- \
+   http://localhost:5000/api/v1/namespaces/default/data
+
+

Example data response from Blob upload

+

Status: 200 OK - your data is uploaded to your local FireFly node

+

At this point the data has not be shared with anyone else in the network

+
{
+  // A uniquely generated ID, we can refer to when sending this data to other parties
+  "id": "97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8",
+  "validator": "json", // the "value" part is JSON
+  "namespace": "default", // from the URL
+  // The hash is a combination of the hash of the "value" metadata, and the
+  // hash of the blob
+  "hash": "997af6a9a19f06cc8a46872617b8bf974b106f744b2e407e94cc6959aa8cf0b8",
+  "created": "2021-07-01T20:20:35.5462306Z",
+  "value": {
+    "filename": "-", // dash is how curl represents the filename for stdin
+    "size": 31185 // the size of the blob data
+  },
+  "blob": {
+    // A hash reference to the blob
+    "hash": "86e6b39b04b605dd1b03f70932976775962509d29ae1ad2628e684faabe48136"
+  }
+}
+
+

Send the uploaded data privately

+

Just include a reference to the id returned from the upload.

+

POST /api/v1/namespaces/default/messages/private

+
{
+  "data": [
+    {
+      "id": "97eb750f-0d0b-4c1d-9e37-1e92d1a22bb8"
+    }
+  ],
+  "group": {
+    "members": [
+      {
+        "identity": "org_1"
+      }
+    ]
+  }
+}
+
+

Sending Private Messages using the Sandbox

+

All of the functionality discussed above can be done through the FireFly Sandbox.

+

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.

+

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

+

Private Message Broadcast

+

Notice how the data field in the center panel updates in real time as you update the message you wish to send.

+

Click the blue Run button. This should return a 202 response immediately in the Server Response section and will populate the right hand panel with transaction information after a few seconds.

+

Private Message result

+

Go back to the FireFly UI (the URL for this would have been shown in the terminal when you started the stack) and you'll see your successful blockchain transaction. Compare the "Recent Network Changes" widget With private messages, your

+

Successful Transaction

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/query_messages/index.html b/v1.3.1/tutorials/query_messages/index.html new file mode 100644 index 000000000..b208a7f16 --- /dev/null +++ b/v1.3.1/tutorials/query_messages/index.html @@ -0,0 +1,3628 @@ + + + + + + + + + + + + + + + + + + + + + + + Explore messages - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Explore messages

+

Quick reference

+

The FireFly Explorer is a great way to view the messages sent and received by your node.

+

Just open /ui on your FireFly node to access it.

+

Explore Messages

+

This builds on the APIs to query and filter messages, described below

+

Additional info

+ +

Example 1: Query confirmed messages

+

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.

+
+

The order in which you process messages should be determined by absolute +order of message_confirmed events - queryable via the events collection, or +through event listeners (discussed next in the getting started guide).

+

That is because messages are ordered by timestamp, +which is potentially subject to adjustments of the clock. +Whereas events are ordered by the insertion order into the database, and as such +changes in the clock do not affect the order.

+
+

GET /api/v1/namespaces/{ns}/messages?pending=false&limit=100

+

Example response

+
[
+  {
+    "header": {
+      "id": "423302bb-abfc-4d64-892d-38b2fdfe1549",
+      "type": "private", // this was a private send
+      "txtype": "batch_pin", // pinned in a batch to the blockchain
+      "author": "0x1d14b65d2dd5c13f6cb6d3dc4aa13c795a8f3b28",
+      "created": "2021-07-02T03:09:40.2606238Z",
+      "namespace": "default",
+      "group": "2aa5297b5eed0c3a612a667c727ca38b54fb3b5cc245ebac4c2c7abe490bdf6c", // sent to this group
+      "topic": ["widget_id_12345"],
+      "tag": "new_widget_created",
+      "datahash": "551dd261e80ce76b1908c031cff8a707bd76376d6eddfdc1040c2ed6481ec8dd"
+    },
+    "hash": "bf2ca94db8c31bae3cae974bb626fa822c6eee5f572d274d72281e72537b30b3",
+    "batch": "f7ac773d-885a-4d73-ac6b-c09f5346a051", // the batch ID that pinned this message to the chain
+    "state": "confirmed", // message is now confirmed
+    "confirmed": "2021-07-02T03:09:49.9207211Z", // timestamp when this node confirmed the message
+    "data": [
+      {
+        "id": "914eed77-8789-451c-b55f-ba9570a71eba",
+        "hash": "9541cabc750c692e553a421a6c5c07ebcae820774d2d8d0b88fac2a231c10bf2"
+      }
+    ],
+    "pins": [
+      // A "pin" is an identifier that is used by FireFly for sequencing messages.
+      //
+      // For private messages, it is an obfuscated representation of the sequence of this message,
+      // on a topic, within this group, from this sender. There will be one pin per topic. You will find these
+      // pins in the blockchain transaction, as well as the off-chain data.
+      // Each one is unqiue, and without the group hash, very difficult to correlate - meaning
+      // the data on-chain provides a high level of privacy.
+      //
+      // Note for broadcast (which does not require obfuscation), it is simply a hash of the topic.
+      // So you will see the same pin for all messages on the same topic.
+      "ee56de6241522ab0ad8266faebf2c0f1dc11be7bd0c41d847998135b45685b77"
+    ]
+  }
+]
+
+

Example 2: Query all messages

+

The natural sort order the API will return for messages is:

+
    +
  • Pending messages first
    • +
  • In descending created timestamp order
    • +
  • Confirmed messages
    • +
  • In descending confirmed timestamp order
    • +
+

GET /api/v1/namespaces/{ns}/messages

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/rotate_dx_certs/index.html b/v1.3.1/tutorials/rotate_dx_certs/index.html new file mode 100644 index 000000000..ac0e3e870 --- /dev/null +++ b/v1.3.1/tutorials/rotate_dx_certs/index.html @@ -0,0 +1,3738 @@ + + + + + + + + + + + + + + + + + + + + + + + Rotate DX Certs - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Rotate DX Certs

+ +

Quick reference

+

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.

+
+

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.

+
+

The high level steps to the process (described in detail below) are:

+
    +
  • Generate new certs and keys
    • +
  • Install new certs and keys on each Data Exchange filesystem
    • +
  • Remove old certs from the peer-certs directory
    • +
  • Restart each Data Exchange process
    • +
  • PATCH the node identity using the FireFly API
    • +
+

Generate new certs and keys

+

To generate a new cert, we're going to use a self signed certificate generated by openssl. This is how the FireFly CLI generated the original cert that was used when it created your stack.

+

For the first member of a FireFly stack you run:

+
openssl req -new -x509 -nodes -days 365 -subj /CN=dataexchange_0/O=member_0 -keyout key.pem -out cert.pem
+
+

For the second member:

+
openssl req -new -x509 -nodes -days 365 -subj /CN=dataexchange_1/O=member_1 -keyout key.pem -out cert.pem
+
+
+

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.

+
+

Install the new certs on each Data Exchange File System

+

For a dev environment created with the FireFly CLI, the certificate and key will be located in the /data directory on the Data Exchange node's file system. You can use the docker cp command to copy the file to the correct location, then set the file ownership correctly.

+
docker cp cert.pem dev_dataexchange_0:/data/cert.pem
+docker exec dev_dataexchange_0 chown root:root /data/cert.pem
+
+
+

NOTE: If your environment is not called dev you may need to change the beginning of the container name in the Docker commands listed in this guide.

+
+

Remove old certs from the peer-certs directory

+

To clear out the old certs from the first Data Exchange node run:

+
docker exec dev_dataexchange_0 sh -c "rm /data/peer-certs/*.pem"
+
+

To clear out the old certs from the second Data Exchange node run:

+
docker exec dev_dataexchange_1 sh -c "rm /data/peer-certs/*.pem"
+
+

Restart each Data Exchange process

+

To restart your Data Exchange processes, run:

+
docker restart dev_dataexchange_0
+
+
docker restart dev_dataexchange_1
+
+

PATCH the node identity using the FireFly API

+

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.

+

Request

+

GET http://localhost:5000/api/v1/namespaces/default/identities

+

Response

+

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:

+
...
+    {
+        "id": "20da74a2-d4e6-4eaf-8506-e7cd205d8254",
+        "did": "did:firefly:node/node_2b9630",
+        "type": "node",
+        "parent": "41e93d92-d0da-4e5a-9cee-adf33f017a60",
+        "namespace": "default",
+        "name": "node_2b9630",
+        "profile": {
+            "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",
+            "endpoint": "https://dataexchange_0:3001",
+            "id": "member_0/node_2b9630"
+        },
+        "messages": {
+            "claim": "95da690b-bb05-4873-9478-942f607f363a",
+            "verification": null,
+            "update": null
+        },
+        "created": "2023-02-06T14:02:50.874319382Z",
+        "updated": "2023-02-06T14:02:50.874319382Z"
+    },
+...
+
+

Copy the UUID from the id field, and add that to the PATCH request. In this case it is 20da74a2-d4e6-4eaf-8506-e7cd205d8254.

+

Request

+

Now we will send the new certificate to FireFly. Put the contents of your cert.pem file in the cert field.

+
+

NOTE: Usually the cert.pem file will contain line breaks which will not be handled correctly by JSON parsers. Be sure to replace those line breaks with \n so that the cert field is all on one line as shown below.

+
+

PATCH http://localhost:5000/api/v1/namespaces/default/identities/20da74a2-d4e6-4eaf-8506-e7cd205d8254

+
{
+  "profile": {
+    "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",
+    "endpoint": "https://dataexchange_0:3001",
+    "id": "member_0"
+  }
+}
+
+

Response

+
{
+  "id": "20da74a2-d4e6-4eaf-8506-e7cd205d8254",
+  "did": "did:firefly:node/node_2b9630",
+  "type": "node",
+  "parent": "41e93d92-d0da-4e5a-9cee-adf33f017a60",
+  "namespace": "default",
+  "name": "node_2b9630",
+  "profile": {
+    "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",
+    "endpoint": "https://dataexchange_0:3001",
+    "id": "member_0"
+  },
+  "messages": {
+    "claim": "95da690b-bb05-4873-9478-942f607f363a",
+    "verification": null,
+    "update": "5782cd7c-7643-4d7f-811b-02765a7aaec5"
+  },
+  "created": "2023-02-06T14:02:50.874319382Z",
+  "updated": "2023-02-06T14:02:50.874319382Z"
+}
+
+

Repeat these requests for the second member/node running on port 5001. After that you should be back up and running with your new certs, and you should be able to send private messages again.

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/tokens/erc1155/index.html b/v1.3.1/tutorials/tokens/erc1155/index.html new file mode 100644 index 000000000..26df6e076 --- /dev/null +++ b/v1.3.1/tutorials/tokens/erc1155/index.html @@ -0,0 +1,3864 @@ + + + + + + + + + + + + + + + + + + + + + + + ERC-1155 - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Use ERC-1155 tokens

+

Previous steps: Install the FireFly CLI

+

If you haven't set up the FireFly CLI already, please go back to the Getting Started guide and read the section on how to Install the FireFly CLI.

+

← ① Install the FireFly CLI

+

Create a stack with an ERC-1155 connector

+

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:

+
ff init ethereum -t erc-1155
+
+

Then run:

+
ff start <your_stack_name>
+
+

About the sample token contract

+

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.

+
⚠️ 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.
+ +

Use the Sandbox (optional)

+

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. +Tokens Sandbox

+

Create a pool (using default token contract)

+

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 name and type (fungible or nonfungible) for the pool.

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

+
+

NOTE: Without passing the query parameter publish=true 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 /tokens/pools/{nameOrId}/publish

+
+
{
+  "name": "testpool",
+  "type": "fungible"
+}
+
+

Other parameters:

+
    +
  • You must specify a connector if you have configured multiple token connectors
    • +
  • You may pass through a config object of additional parameters, if supported by your token connector
    • +
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
    • +
+

Create a pool (from a deployed token contract)

+

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.

+

See the README of the token connector for details on what contract variants can currently be understood.

+

You can pass a config object with an address when you make the request to create the token pool, and if you created a contract interface, you can include the interface ID as well.

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

+
+

NOTE: Without passing the query parameter publish=true 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 /tokens/pools/{nameOrId}/publish

+
+
{
+  "name": "testpool",
+  "type": "fungible",
+  "interface": {
+    "id": "b9e5e1ce-97bb-4a35-a25c-52c7c3f523d8"
+  },
+  "config": {
+    "address": "0xb1C845D32966c79E23f733742Ed7fCe4B41901FC"
+  }
+}
+
+

Mint tokens

+

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.

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint

+
{
+  "amount": 10
+}
+
+

Other parameters:

+
    +
  • You must specify a pool name if you've created more than one pool
    • +
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
    • +
  • You may specify to if you'd like to send the minted tokens to a specific identity (default is the same as key)
    • +
+

Transfer tokens

+

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.

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

+
{
+  "amount": 1,
+  "to": "0x07eab7731db665caf02bc92c286f51dea81f923f"
+}
+
+
+

NOTE: When transferring a non-fungible token, the amount must always be 1. The tokenIndex field is also required when transferring a non-fungible token.

+
+

Other parameters:

+
    +
  • You must specify a pool name if you've created more than one pool
    • +
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
    • +
  • You may specify from if you'd like to send tokens from a specific identity (default is the same as key)
    • +
+

Sending data with a transfer

+

All transfers (as well as mint/burn operations) support an optional message 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.

+

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.

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

+

Broadcast message

+
{
+  "amount": 1,
+  "to": "0x07eab7731db665caf02bc92c286f51dea81f923f",
+  "message": {
+    "data": [
+      {
+        "value": "payment for goods"
+      }
+    ]
+  }
+}
+
+

Private message

+
{
+  "amount": 1,
+  "to": "0x07eab7731db665caf02bc92c286f51dea81f923f",
+  "message": {
+    "header": {
+      "type": "transfer_private"
+    },
+    "group": {
+      "members": [
+        {
+          "identity": "org_1"
+        }
+      ]
+    },
+    "data": [
+      {
+        "value": "payment for goods"
+      }
+    ]
+  }
+}
+
+

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.

+

Burn tokens

+

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.

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn

+
{
+  "amount": 1
+}
+
+
+

NOTE: When burning a non-fungible token, the amount must always be 1. The tokenIndex field is also required when burning a non-fungible token.

+
+

Other parameters:

+
    +
  • You must specify a pool name if you've created more than one pool
    • +
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
    • +
  • You may specify from if you'd like to burn tokens from a specific identity (default is the same as key)
    • +
+

Token approvals

+

You can also approve other wallets to transfer tokens on your behalf with the /approvals API. The important fields in a token approval API request are as follows:

+
    +
  • approved: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to true. Setting to false can revoke an existing approval.
    • +
  • operator: The other account that is allowed to transfer tokens out of the wallet specified in the key field
    • +
  • key: The wallet address for the approval. If not set, it defaults to the address of the FireFly node submitting the transaction
    • +
+

Here is an example request that would let the signing account 0x634ee8c7d0894d086c7af1fc8514736aed251528 transfer any amount of tokens from my wallet

+

Request

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals

+
{
+  "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528"
+}
+
+

Response

+
{
+  "localId": "46fef50a-cf93-4f92-acf8-fae161b37362",
+  "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d",
+  "connector": "erc1155",
+  "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528",
+  "approved": true,
+  "tx": {
+    "type": "token_approval",
+    "id": "00faa011-f42c-403d-a047-2df7318967cd"
+  }
+}
+
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/tokens/erc20/index.html b/v1.3.1/tutorials/tokens/erc20/index.html new file mode 100644 index 000000000..a118942c5 --- /dev/null +++ b/v1.3.1/tutorials/tokens/erc20/index.html @@ -0,0 +1,4089 @@ + + + + + + + + + + + + + + + + + + + + + + + ERC-20 - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Use ERC-20 tokens

+

Previous steps: Start your environment

+

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.

+

← ② Start your environment

+

About the sample token contracts

+

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 type in the API request.

+
⚠️ 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.
+ +

Use the Sandbox (optional)

+

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. +Tokens Sandbox

+

Create a pool (using default token factory)

+

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 name and type for the pool.

+

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.

+

Request

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

+
+

NOTE: Without passing the query parameter publish=true 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 /tokens/pools/{nameOrId}/publish

+
+
{
+  "name": "testpool",
+  "type": "fungible"
+}
+
+

Response

+
{
+  "id": "e1477ed5-7282-48e5-ad9d-1612296bb29d",
+  "type": "fungible",
+  "namespace": "default",
+  "name": "testpool",
+  "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "connector": "erc20_erc721",
+  "tx": {
+    "type": "token_pool",
+    "id": "e901921e-ffc4-4776-b20a-9e9face70a47"
+  },
+  "published": true
+}
+
+

Other parameters:

+
    +
  • You must specify a connector if you have configured multiple token connectors
    • +
  • You may pass through a config object of additional parameters, if supported by your token connector
    • +
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
    • +
+

Get the address of the deployed contract

+

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 GET request to the pool's ID:

+

Request

+

GET http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools/5811e8d5-52d0-44b1-8b75-73f5ff88f598

+

Response

+
{
+  "id": "e1477ed5-7282-48e5-ad9d-1612296bb29d",
+  "type": "fungible",
+  "namespace": "default",
+  "name": "testpool",
+  "standard": "ERC20",
+  "locator": "address=0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c&schema=ERC20WithData&type=fungible",
+  "decimals": 18,
+  "connector": "erc20_erc721",
+  "message": "7e2f6004-31fd-4ba8-9845-15c5fe5fbcd7",
+  "state": "confirmed",
+  "created": "2022-04-28T14:03:16.732222381Z",
+  "info": {
+    "address": "0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c",
+    "name": "testpool",
+    "schema": "ERC20WithData"
+  },
+  "tx": {
+    "type": "token_pool",
+    "id": "e901921e-ffc4-4776-b20a-9e9face70a47"
+  }
+}
+
+

Create a pool (from a deployed token contract)

+

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.

+

See the README of the token connector for details on what contract variants can currently be understood.

+

You can pass a config object with an address and blockNumber when you make the request to create the token pool, and if you created a contract interface, you can include the interface ID as well.

+

Request

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

+
+

NOTE: Without passing the query parameter publish=true 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 /tokens/pools/{nameOrId}/publish

+
+
{
+  "name": "testpool",
+  "type": "fungible",
+  "interface": {
+    "id": "b9e5e1ce-97bb-4a35-a25c-52c7c3f523d8"
+  },
+  "config": {
+    "address": "0xb1C845D32966c79E23f733742Ed7fCe4B41901FC",
+    "blockNumber": "0"
+  }
+}
+
+

Mint tokens

+

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.

+
+

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×1018 = 100000000000000000000. This allows users to work with "fractional" tokens even though Ethereum virtual machines only support integer arithmetic.

+
+

Request

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint

+
{
+  "amount": "100000000000000000000"
+}
+
+

Response

+
{
+  "type": "mint",
+  "localId": "835fe2a1-594b-4336-bc1d-b2f59d51064b",
+  "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d",
+  "connector": "erc20_erc721",
+  "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "from": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "to": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "amount": "100000000000000000000",
+  "tx": {
+    "type": "token_transfer",
+    "id": "3fc97e24-fde1-4e80-bd82-660e479c0c43"
+  }
+}
+
+

Other parameters:

+
    +
  • You must specify a pool name if you've created more than one pool
    • +
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
    • +
  • You may specify to if you'd like to send the minted tokens to a specific identity (default is the same as key)
    • +
+

Transfer tokens

+

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.

+

Request

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

+
{
+  "amount": "10000000000000000000",
+  "to": "0xa4222a4ae19448d43a338e6586edd5fb2ac398e1"
+}
+
+

Response

+
{
+  "type": "transfer",
+  "localId": "61f0a71f-712b-4778-8b37-784fbee52657",
+  "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d",
+  "connector": "erc20_erc721",
+  "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "from": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "to": "0xa4222a4ae19448d43a338e6586edd5fb2ac398e1",
+  "amount": "10000000000000000000",
+  "tx": {
+    "type": "token_transfer",
+    "id": "c0c316a3-23a9-42f3-89b3-1cfdba6c948d"
+  }
+}
+
+

Other parameters:

+
    +
  • You must specify a pool name if you've created more than one pool
    • +
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
    • +
  • You may specify from if you'd like to send tokens from a specific identity (default is the same as key)
    • +
+

Sending data with a transfer

+

All transfers (as well as mint/burn operations) support an optional message 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.

+

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.

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

+

Broadcast message

+
{
+  "amount": 1,
+  "to": "0x07eab7731db665caf02bc92c286f51dea81f923f",
+  "message": {
+    "data": [
+      {
+        "value": "payment for goods"
+      }
+    ]
+  }
+}
+
+

Private message

+
{
+  "amount": 1,
+  "to": "0x07eab7731db665caf02bc92c286f51dea81f923f",
+  "message": {
+    "header": {
+      "type": "transfer_private"
+    },
+    "group": {
+      "members": [
+        {
+          "identity": "org_1"
+        }
+      ]
+    },
+    "data": [
+      {
+        "value": "payment for goods"
+      }
+    ]
+  }
+}
+
+

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.

+

Burn tokens

+

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.

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn

+
{
+  "amount": 1
+}
+
+

Other parameters:

+
    +
  • You must specify a pool name if you've created more than one pool
    • +
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
    • +
  • You may specify from if you'd like to burn tokens from a specific identity (default is the same as key)
    • +
+

Token approvals

+

You can also approve other wallets to transfer tokens on your behalf with the /approvals API. The important fields in a token approval API request are as follows:

+
    +
  • approved: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to true. Setting to false can revoke an existing approval.
    • +
  • operator: The other account that is allowed to transfer tokens out of the wallet specified in the key field.
    • +
  • config.allowance: The number of tokens the other account is allowed to transfer. If 0 or not set, the approval is valid for any number.
    • +
  • key: The wallet address for the approval. If not set, it defaults to the address of the FireFly node submitting the transaction.
    • +
+

Here is an example request that would let the signing account 0x634ee8c7d0894d086c7af1fc8514736aed251528 transfer up to 10×1018 (10000000000000000000) tokens from my wallet

+

Request

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals

+
{
+  "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528",
+  "config": {
+    "allowance": "10000000000000000000"
+  }
+}
+
+

Response

+
{
+  "localId": "46fef50a-cf93-4f92-acf8-fae161b37362",
+  "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d",
+  "connector": "erc20_erc721",
+  "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528",
+  "approved": true,
+  "tx": {
+    "type": "token_approval",
+    "id": "00faa011-f42c-403d-a047-2df7318967cd"
+  },
+  "config": {
+    "allowance": "10000000000000000000"
+  }
+}
+
+

Use Metamask

+

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.

+

Configure a new network

+

The first thing we need to do is tell Metamask how to connect to our local blockchain node. To do that:

+
    +
  • Click your account icon
    • +
  • +

    In the drop down menu, click Settings + Metamask Settings

    +
    • +
  • +

    On the left hand side of the page, click Networks

    +
    • +
  • +

    Click the Add a network button + Metamask Add Network

    +
    • +
  • +

    Fill in the network details:

    +
    • +
  • Network Name: FireFly (could be any name)
    • +
  • New RPC URL: http://127.0.0.1:5100
    • +
  • Chain ID: 2021
    • +
  • Currency Symbol: ETH
    • +
  • Click Save + Metamask Network Details
    • +
+

Import tokens

+

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.

+
    +
  • +

    Click on Import tokens + Metamask Import Tokens

    +
    • +
  • +

    Enter the Ethereum address of the contract

    +
    • +
  • Enter a Token Symbol (can be anything you want)
    • +
  • Click Add Custom Token
    • +
+
+

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 GET to http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools to lookup your configured token pools.

+
+

Metamask Import Tokens

+

Transfer tokens

+

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.

+

Metamask Account Address

+

After a couple seconds, you should see your tokens show up in your Metamask wallet.

+

Metamask Tokens Received

+

You can also send tokens to a FireFly address or any other Ethereum address from your Metamask wallet.

+
+

NOTE: You can find the Ethereum addresses for organizations in your FireFly network in the Network → Organizations page in the FireFly explorer. Click on an organization and look under the Verifiers header for the organization's Ethereum address.

+
+

Metamask Send Tokens

+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/tokens/erc721/index.html b/v1.3.1/tutorials/tokens/erc721/index.html new file mode 100644 index 000000000..7671e58f9 --- /dev/null +++ b/v1.3.1/tutorials/tokens/erc721/index.html @@ -0,0 +1,4098 @@ + + + + + + + + + + + + + + + + + + + + + + + ERC-721 - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Use ERC-721 tokens

+

Previous steps: Start your environment

+

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.

+

← ② Start your environment

+

About the sample token contracts

+

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 type in the API request.

+
⚠️ 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.
+ +

Use the Sandbox (optional)

+

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. +Tokens Sandbox

+

Create a pool (using default token factory)

+

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 name and type for the pool.

+

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.

+

Request

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

+
+

NOTE: Without passing the query parameter publish=true 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 /tokens/pools/{nameOrId}/publish

+
+
{
+  "type": "nonfungible",
+  "name": "nfts"
+}
+
+

Response

+
{
+  "id": "a92a0a25-b886-4b43-931f-4add2840258a",
+  "type": "nonfungible",
+  "namespace": "default",
+  "name": "nfts",
+  "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "connector": "erc20_erc721",
+  "tx": {
+    "type": "token_pool",
+    "id": "00678116-89d2-4295-990c-bd5ffa6e2434"
+  },
+  "published": true
+}
+
+

Other parameters:

+
    +
  • You must specify a connector if you have configured multiple token connectors
    • +
  • You may pass through a config object of additional parameters, if supported by your token connector
    • +
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
    • +
+

Get the address of the deployed contract

+

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 GET request to the pool's ID:

+

Request

+

GET http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools/5811e8d5-52d0-44b1-8b75-73f5ff88f598

+

Response

+
{
+  "id": "a92a0a25-b886-4b43-931f-4add2840258a",
+  "type": "nonfungible",
+  "namespace": "default",
+  "name": "nfts",
+  "standard": "ERC721",
+  "locator": "address=0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c&schema=ERC721WithData&type=nonfungible",
+  "connector": "erc20_erc721",
+  "message": "53d95dda-e8ca-4546-9226-a0fdc6ec03ec",
+  "state": "confirmed",
+  "created": "2022-04-29T12:03:51.971349509Z",
+  "info": {
+    "address": "0xc4d02efcfab06f18ec0a68e00b98ffecf6bf7e3c",
+    "name": "nfts",
+    "schema": "ERC721WithData"
+  },
+  "tx": {
+    "type": "token_pool",
+    "id": "00678116-89d2-4295-990c-bd5ffa6e2434"
+  }
+}
+
+

Create a pool (from a deployed token contract)

+

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.

+

See the README of the token connector for details on what contract variants can currently be understood.

+

You can pass a config object with an address and blockNumber when you make the request to create the token pool, and if you created a contract interface, you can include the interface ID as well.

+

Request

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools?publish=true

+
+

NOTE: Without passing the query parameter publish=true 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 /tokens/pools/{nameOrId}/publish

+
+
{
+  "name": "testpool",
+  "type": "nonfungible",
+  "interface": {
+    "id": "b9e5e1ce-97bb-4a35-a25c-52c7c3f523d8"
+  },
+  "config": {
+    "address": "0xb1C845D32966c79E23f733742Ed7fCe4B41901FC",
+    "blockNumber": "0"
+  }
+}
+
+

Mint a token

+

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:

+
    +
  • only the creator of a pool is allowed to mint within that pool
    • +
  • the tokenIndex must be set to a unique value
    • +
  • the amount must be 1
    • +
+

A different ERC-721 contract may define its own requirements.

+

Request

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/mint

+
{
+  "amount": "1",
+  "tokenIndex": "1"
+}
+
+

Response

+
{
+  "type": "mint",
+  "localId": "2de2e05e-9474-4a08-a64f-2cceb076bdaa",
+  "pool": "a92a0a25-b886-4b43-931f-4add2840258a",
+  "connector": "erc20_erc721",
+  "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "from": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "to": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "amount": "1",
+  "tx": {
+    "type": "token_transfer",
+    "id": "0fad4581-7cb2-42c7-8f78-62d32205c2c2"
+  }
+}
+
+

Other parameters:

+
    +
  • You must specify a pool name if you've created more than one pool
    • +
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
    • +
  • You may specify to if you'd like to send the minted tokens to a specific identity (default is the same as key)
    • +
+

Transfer a token

+

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.

+

When transferring an NFT, you must also specify the tokenIndex that you wish to transfer. The tokenIndex is simply the ID of the specific NFT within the pool that you wish to transfer.

+
+

NOTE: When transferring NFTs the amount must be 1. If you wish to transfer more NFTs, simply call the endpoint multiple times, specifying the token index of each token to transfer.

+
+

Request

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

+
{
+  "amount": "1",
+  "tokenIndex": "1",
+  "to": "0xa4222a4ae19448d43a338e6586edd5fb2ac398e1"
+}
+
+

Response

+
{
+  "type": "transfer",
+  "localId": "f5fd0d13-db13-4d70-9a99-6bcd747f1e42",
+  "pool": "a92a0a25-b886-4b43-931f-4add2840258a",
+  "tokenIndex": "1",
+  "connector": "erc20_erc721",
+  "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "from": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "to": "0xa4222a4ae19448d43a338e6586edd5fb2ac398e1",
+  "amount": "1",
+  "tx": {
+    "type": "token_transfer",
+    "id": "63c1a89b-240c-41eb-84bb-323d56f4ba5a"
+  }
+}
+
+

Other parameters:

+
    +
  • You must specify a pool name if you've created more than one pool
    • +
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
    • +
  • You may specify from if you'd like to send tokens from a specific identity (default is the same as key)
    • +
+

Sending data with a transfer

+

All transfers (as well as mint/burn operations) support an optional message 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.

+

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.

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/transfers

+

Broadcast message

+
{
+  "amount": 1,
+  "tokenIndex": "1",
+  "to": "0x07eab7731db665caf02bc92c286f51dea81f923f",
+  "message": {
+    "data": [
+      {
+        "value": "payment for goods"
+      }
+    ]
+  }
+}
+
+

Private message

+
{
+  "amount": 1,
+  "tokenIndex": "1",
+  "to": "0x07eab7731db665caf02bc92c286f51dea81f923f",
+  "message": {
+    "header": {
+      "type": "transfer_private"
+    },
+    "group": {
+      "members": [
+        {
+          "identity": "org_1"
+        }
+      ]
+    },
+    "data": [
+      {
+        "value": "payment for goods"
+      }
+    ]
+  }
+}
+
+

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.

+

Burn tokens

+

You may burn a token by specifying the token's tokenIndex. 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.

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/burn

+
{
+  "amount": 1,
+  "tokenIndex": "1"
+}
+
+

Other parameters:

+
    +
  • You must specify a pool name if you've created more than one pool
    • +
  • You may specify a key understood by the connector (i.e. an Ethereum address) if you'd like to use a non-default signing identity
    • +
  • You may specify from if you'd like to burn tokens from a specific identity (default is the same as key)
    • +
+

Token approvals

+

You can also approve other wallets to transfer tokens on your behalf with the /approvals API. The important fields in a token approval API request are as follows:

+
    +
  • approved: Sets whether another account is allowed to transfer tokens out of this wallet or not. If not specified, will default to true. Setting to false can revoke an existing approval.
    • +
  • operator: The other account that is allowed to transfer tokens out of the wallet specified in the key field
    • +
  • config.tokenIndex: The specific token index within the pool that the operator is allowed to transfer. If 0 or not set, the approval is valid for all tokens.
    • +
  • key: The wallet address for the approval. If not set, it defaults to the address of the FireFly node submitting the transaction
    • +
+

Here is an example request that would let the signing account 0x634ee8c7d0894d086c7af1fc8514736aed251528 transfer tokenIndex 2 from my wallet.

+

Request

+

POST http://127.0.0.1:5000/api/v1/namespaces/default/tokens/approvals

+
{
+  "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528",
+  "config": {
+    "tokenIndex": "2"
+  }
+}
+
+

Response

+
{
+  "localId": "46fef50a-cf93-4f92-acf8-fae161b37362",
+  "pool": "e1477ed5-7282-48e5-ad9d-1612296bb29d",
+  "connector": "erc20_erc721",
+  "key": "0x14ddd36a0c2f747130915bf5214061b1e4bec74c",
+  "operator": "0x634ee8c7d0894d086c7af1fc8514736aed251528",
+  "approved": true,
+  "tx": {
+    "type": "token_approval",
+    "id": "00faa011-f42c-403d-a047-2df7318967cd"
+  },
+  "config": {
+    "tokenIndex": "2"
+  }
+}
+
+

Use Metamask

+

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.

+

Configure a new network

+

The first thing we need to do is tell Metamask how to connect to our local blockchain node. To do that:

+
    +
  • Click your account icon
    • +
  • +

    In the drop down menu, click Settings + Metamask Settings

    +
    • +
  • +

    On the left hand side of the page, click Networks

    +
    • +
  • +

    Click the Add a network button + Metamask Add Network

    +
    • +
  • +

    Fill in the network details:

    +
    • +
  • Network Name: FireFly (could be any name)
    • +
  • New RPC URL: http://127.0.0.1:5100
    • +
  • Chain ID: 2021
    • +
  • Currency Symbol: ETH
    • +
  • Click Save + Metamask Network Details
    • +
+

Import tokens

+

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.

+
    +
  • +

    Click on Import tokens + Metamask Import Tokens

    +
    • +
  • +

    Enter the Ethereum address of the contract

    +
    • +
  • Enter a Token Symbol (can be anything you want)
    • +
  • Click Add Custom Token
    • +
+
+

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 GET to http://127.0.0.1:5000/api/v1/namespaces/default/tokens/pools to lookup your configured token pools.

+
+

Metamask Import Tokens

+

Transfer tokens

+

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.

+

Metamask Account Address

+

After a couple seconds, you should see your token show up in your Metamask wallet.

+

Metamask Tokens Received

+
+

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.

+
+ + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/tutorials/tokens/index.html b/v1.3.1/tutorials/tokens/index.html new file mode 100644 index 000000000..aace2797a --- /dev/null +++ b/v1.3.1/tutorials/tokens/index.html @@ -0,0 +1,3450 @@ + + + + + + + + + + + + + + + + + + + + + + + Use tokens - Hyperledger FireFly + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + +
+
+
+ + + +
+
+
+ + + +
+
+
+ + + +
+
+ + + + + + + +

Use tokens

+ +

Quick reference

+

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.

+
    +
  • FireFly provides an abstraction layer for multiple types of tokens
    • +
  • Tokens are grouped into pools, which each represent a particular type or class of token
    • +
  • Each pool is classified as fungible or non-fungible
    • +
  • In the case of non-fungible tokens, the pool is subdivided into individual tokens with a unique token index
    • +
  • Within a pool, you may mint (issue), transfer, and burn (redeem) tokens
    • +
  • Each operation can be optionally accompanied by a broadcast or private message, which will be recorded alongside the transfer on-chain
    • +
  • FireFly tracks a history of all token operations along with all current token balances
    • +
  • The blockchain backing each token connector may be the same or different from the one backing FireFly message pinning
    • +
+

What is a pool?

+

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:

+
    +
  • ERC-1155: a single contract instance can efficiently allocate + many isolated pools of fungible or non-fungible tokens
    • +
  • ERC-20 / ERC-777: + each contract instance represents a single fungible pool of value, e.g. "a coin"
    • +
  • ERC-721: each contract instance represents a single pool of NFTs, + each with unique identities within the pool
    • +
  • ERC-1400 / ERC-1410: + partially supported in the same manner as ERC-20/ERC-777, but would require new features for working with partitions
    • +
+

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.

+ + + + + + + + + + + + + + + + + + + +
+
+ + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/v1.3.1/versions.json b/v1.3.1/versions.json new file mode 100644 index 000000000..e69de29bb diff --git a/versions.json b/versions.json index 763843e29..26b03982a 100644 --- a/versions.json +++ b/versions.json @@ -4,6 +4,11 @@ "title": "head", "aliases": [] }, + { + "version": "v1.3.1", + "title": "v1.3.1", + "aliases": [] + }, { "version": "v1.3.0", "title": "v1.3.0",

Open the FireFly Sandbox for the first member