Link Search Menu Expand Document


Table of contents

  1. Introduction to Namespaces
    1. Multi-party Namespaces
    2. Gateway Namespaces
  2. Configuration
    1. Config Restrictions
  3. Definitions
  4. Local Definitions

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.


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:

  - name: database0
    type: sqlite3
        auto: true
      url: /etc/firefly/db?_busy_timeout=5000
  - name: blockchain0
    type: ethereum
        url: http://ethconnect_0:8080
        topic: "0"
  - name: blockchain1
    type: ethereum
        url: http://ethconnect_01:8080
        topic: "0"
  - name: dataexchange0
    type: ffdx
      url: http://dataexchange_0:3000
  - name: sharedstorage0
    type: ipfs
        url: http://ipfs_0:5001
        url: http://ipfs_0:8080
  - name: erc20_erc721
    broadcastName: erc20_erc721
    type: fftokens
      url: http://tokens_0_0:3000
  default: alpha
  - name: alpha
    description: Default predefined namespace
    defaultKey: 0x123456
    plugins: [database0, blockchain0, dataexchange0, sharedstorage0, erc20_erc721]
      networkNamespace: alpha
      enabled: true
        name: org0
        description: org0
        key: 0x123456
        name: node0
        description: node0
        - 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)
  • 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.


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)