Uploaded image for project: 'Fabric'
  1. Fabric
  2. FAB-5363

Common "connection profile" definition for client applications



      All applications have a need to capture information of the target fabric backend and associated materials (eg. MSP and TLS certificates).

      The general idea is that a client/channel instance can be initialized directly from the connection profile, and have a code snippet like the following:

      1. var client = Client.loadFromConfig(json)
      2. var mychannel = client.getChannel('mychannel')
      3. mychannel.sendTransactionProposal()
      4. mychannel.sendTransaction()

      note that the app then doesn't need to manually construct the channel, add peers, add orderers, get the org admin, etc.

      The latest design resulted from the discussions

      # The network connection profile provides client applications the information about the target
      # blockchain network that are necessary for the applications to interact with it. These are all 
      # knowledge that must be acquired from out-of-band sources. This file provides such a source.
      name: "global-trade-network"
      # Any properties with an "x-" prefix will be treated as application-specific, exactly like how naming
      # in HTTP headers or swagger properties work. The SDK will simply ignore these fields and leave
      # them for the applications to process. This is a mechanism for different components of an application
      # to exchange information that are not part of the standard schema described below. In particular,
      # the "x-type" property with the "hlfv1" value example below is used by Hyperledger Composer to
      # determine the type of Fabric networks (v0.6 vs. v1.0) it needs to work with.
      x-type: "hlfv1"
      x-loggingLevel: info
      # Describe what the target network is/does.
      description: "The network to be in if you want to stay in the global trade business"
      # Schema version of the content. Used by the SDK to apply the corresponding parsing rules.
      version: 1.0.0
      # The client section is SDK-specific. The sample below is for the node.js SDK
        # Which organization does this application instance belong to? The value must be the name of an org
        # defined under "organizations"
        organization: Org1
        # set connection timeouts for the peer and orderer for the client
            endorser: 3s
            eventHub: 3s
            eventReg: 3s
           orderer: 3s
        # Needed to load users crypto keys and certs.
          path: path/to/fixtures/channel/crypto-config
        # Some SDKs support pluggable KV stores, the properties under "credentialStore" 
        # are implementation specific
          # [Optional]. Specific to FileKeyValueStore.js or similar implementations in other SDKs. Can be others
          # if using an alternative impl. For instance, CouchDBKeyValueStore.js would require an object
          # here for properties like url, db name, etc.
          path: "/tmp/hfc-kvs"
          # [Optional]. Specific to the CryptoSuite implementation. Software-based implementations like 
          # CryptoSuite_ECDSA_AES.js in node SDK requires a key store. PKCS#11 based implementations does 
          # not.
            # Specific to the underlying KeyValueStore that backs the crypto key store. 
            path: "/tmp/hfc-cvs"
          # [Optional]. Specific to Composer environment
          wallet: wallet-name
        # BCCSP config for the client.
          enabled: true
           provider: "SW"
          hashAlgorithm: "SHA2"
          softVerify: true
          ephemeral: false
          level: 256
          pin: "12345678"
          label: "ForFabric"
          library: /path/to/bccsp/libraries
      # [Optional]. But most apps would have this section so that channel objects can be constructed 
      # based on the content below. If an app is creating channels, then it likely will not need this 
      # section.
        # name of the channel
          # Required. list of orderers designated by the application to use for transactions on this 
          # channel. This list can be a result of access control ("org1" can only access "ordererA"), or 
          # operational decisions to share loads from applications among the orderers.  The values must 
          # be "names" of orgs defined under "organizations/peers"
            - orderer.example.com
          # Required. list of peers from participating orgs
              # [Optional]. will this peer be sent transaction proposals for endorsement? The peer must 
              # have the chaincode installed. The app can also use this property to decide which peers 
              # to send the chaincode install request. Default: true
              endorsingPeer: true
              # [Optional]. will this peer be sent query proposals? The peer must have the chaincode
              # installed. The app can also use this property to decide which peers to send the 
              # chaincode install request. Default: true
              chaincodeQuery: true
              # [Optional]. will this peer be sent query proposals that do not require chaincodes, like 
              # queryBlock(), queryTransaction(), etc. Default: true
              ledgerQuery: true
              # [Optional]. will this peer be the target of the SDK's listener registration? All peers can 
              # produce events but the app typically only needs to connect to one to listen to events. 
              # Default: true
              eventSource: true
              endorsingPeer: true
              chaincodeQuery: false
              ledgerQuery: true
              eventSource: false
          # [Optional]. what chaincodes are expected to exist on this channel? The application can use
          # this information to validate that the target peers are in the expected state by comparing
          # this list with the query results of getInstalledChaincodes() and getInstantiatedChaincodes()
            # the format follows the "cannonical name" of chaincodes by fabric code
            - example02:v1
            - marbles:1.0
      # list of participating organizations in this network
          mspid: Org1MSP
            - peer0.org1.example.com
            - peer1.org1.example.com
          # [Optional]. Certificate Authorities issue certificates for identification purposes in a Fabric based
          # network. Typically certificates provisioning is done in a separate process outside of the 
          # runtime network. Fabric-CA is a special certificate authority that provides a REST APIs for 
          # dynamic certificate management (enroll, revoke, re-enroll). The following section is only for 
          # Fabric-CA servers.
            - ca-org1
          # [Optional]. If the application is going to make requests that are reserved to organization 
          # administrators, including creating/updating channels, installing/instantiating chaincodes, it 
          # must have access to the admin identity represented by the private key and signing certificate. 
          # Both properties can be the PEM string or local path to the PEM file. Note that this is mainly for
          # convenience in development mode, production systems should not expose sensitive information
          # this way. The SDK should allow applications to set the org admin identity via APIs, and only use
          # this route as an alternative when it exists.
            pem: "-----BEGIN PRIVATE KEY----- <etc>"
            path: "/tmp/somepath/signed-cert.pem"
        # the profile will contain public information about organizations other than the one it belongs to. 
        # These are necessary information to make transaction lifecycles work, including MSP IDs and 
        # peers with a public URL to send transaction proposals. The file will not contain private 
        # information reserved for members of the organization, such as admin key and certificate, 
        # fabric-ca registrar enroll ID and secret, etc.
          mspid: Org2MSP
            - peer0.org2.example.com
      # List of orderers to send transaction and channel create/update requests to. For the time
      # being only one orderer is needed. If more than one is defined, which one get used by the
      # SDK is implementation specific. Consult each SDK's documentation for its handling of orderers.
          url: grpcs://localhost:7050
          # these are standard properties defined by the gRPC library
          # they will be passed in as-is to gRPC client constructor
            ssl-target-name-override: orderer.example.com
            grpc-max-send-message-length: 15
            pem: "-----BEGIN CERTIFICATE----- <etc> "
      # List of peers to send various requests to, including endorsement, query
      # and event listener registration.
          # this URL is used to send endorsement and query requests
          url: grpcs://localhost:7051
          # this URL is used to connect the EventHub and registering event listeners
          eventUrl: grpcs://localhost:7053
            ssl-target-name-override: peer0.org1.example.com
            grpc.http2.keepalive_time: 15
            # Comma-Separated list of paths
            path: peer0.org1.example.com/tlscacerts/org1.example.com-cert.pem
          url: grpcs://localhost:8051
          eventUrl: grpcs://localhost:8053
            ssl-target-name-override: peer0.org2.example.com
            # Comma-Separated list of paths
            path: peer0.org2.example.com/tlscacerts/org2.example.com-cert.pem
      # Fabric-CA is a special kind of Certificate Authority provided by Hyperledger Fabric which allows 
      # certificate management to be done via REST APIs. Application may choose to use a standard 
      # Certificate Authority instead of Fabric-CA, in which case this section would not be specified.
          url: https://localhost:7054
          # the properties specified under this object are passed to the 'http' client verbatim when
          # making the request to the Fabric-CA server
            verify: true
            # Comma-Separated list of paths
            path: peerOrganizations/org1.example.com/ca/org1.example.com-cert.pem
            # Client key and cert for TLS mutual auth with Fabric CA. If the target Fabric CA server
            # does not have TLS mutual auth turned on, then this section is not needed
              keyfile: path/to/tls/fabricca/certs/client/client_fabric_client-key.pem
              certfile: path/to/tls/fabricca/certs/client/client_fabric_client.pem
          # Fabric-CA supports dynamic user enrollment via REST APIs. A "root" user, a.k.a registrar, is 
          # needed to enroll and invoke new users.
             enrollId: admin
             enrollSecret: adminpw
          # [Optional] The optional name of the CA.
          caName: caNameHere




          Issue Links



              • Assignee:
                harrisob@us.ibm.com Bret Harrison
                jimthematrix Jim Zhang
                Aleksandar Likic, Anthony O'Dowd, Antonio Vassell, Baha A Shaaban, Baohua Yang, Bret Harrison, Chris Poole, Christopher Ferris, Dave Kelsey, David Enyeart, David Huffman, Elisabetta Flamini, Ian Mitchell, Martin Cocks, Qiang Wang, Rick Rine, Simon Stone, Troy Ronda, Yohei Ueda
              • Votes:
                1 Vote for this issue
                19 Start watching this issue


                • Created: