fabric-gateway 0.0.2 → 0.4.0

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "fabric/gateway"
+require 'bundler/setup'
+require 'fabric'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "fabric/gateway"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/bin/regenerate

@@ -16,3 +16,4 @@ grpc_tools_ruby_protoc -I ./fabric-protos --ruby_out=./lib --grpc_out=./lib ./fa
 grpc_tools_ruby_protoc -I ./fabric-protos --ruby_out=./lib --grpc_out=./lib ./fabric-protos/orderer/ab.proto
 grpc_tools_ruby_protoc -I ./fabric-protos --ruby_out=./lib --grpc_out=./lib ./fabric-protos/gossip/message.proto
 grpc_tools_ruby_protoc -I ./fabric-protos --ruby_out=./lib --grpc_out=./lib ./fabric-protos/msp/msp_principal.proto
+grpc_tools_ruby_protoc -I ./fabric-protos --ruby_out=./lib --grpc_out=./lib ./fabric-protos/msp/identities.proto

data/bin/release

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+# Requires gem install gem-release
+# usage: bin/relase -v minor|major|etc.
+gem bump --file lib/fabric/version.rb -t -r $@

data/fabric-gateway.gemspec

@@ -1,31 +1,45 @@
-require_relative 'lib/fabric/gateway/version'
+# frozen_string_literal: true
+
+require_relative 'lib/fabric/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "fabric-gateway"
-  spec.version       = Fabric::Gateway::VERSION
-  spec.authors       = ["Jonathan Chan"]
-  spec.email         = ["jonathan.chan@ethicalidentity.com"]
+  spec.name          = 'fabric-gateway'
+  spec.version       = Fabric::VERSION
+  spec.authors       = ['Jonathan Chan']
+  spec.email         = ['jonathan.chan@ethicalidentity.com']
 
-  spec.summary       = %q{Hyperledger Fabric Gateway gRPC SDK}
-  spec.description   = %q{Hyperledger Fabric Gateway gRPC SDK generated directly from protos found at: https://github.com/hyperledger/fabric-protos.}
-  spec.homepage      = "https://github.com/ethicalidentity/fabric-gateway-ruby"
-  spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+  spec.summary       = 'Hyperledger Fabric Gateway SDK'
+  spec.description   = 'Ruby port of the Hyperledger Fabric Gateway SDK'
+  spec.homepage      = 'https://github.com/ethicalidentity/fabric-gateway-ruby'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
 
-  spec.metadata["allowed_push_host"] = 'https://rubygems.org'
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/ethicalidentity/fabric-gateway-ruby"
-  spec.metadata["changelog_uri"] = "https://github.com/EthicalIdentity/fabric-gateway-ruby/blob/master/CHANGELOG.md"
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/ethicalidentity/fabric-gateway-ruby'
+  spec.metadata['changelog_uri'] = 'https://github.com/EthicalIdentity/fabric-gateway-ruby/blob/master/CHANGELOG.md'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
   spec.add_dependency('google-protobuf', '>= 3.19.1')
   spec.add_dependency('grpc', '~> 1.42')
+  spec.add_development_dependency('codecov', '~> 0.6.0')
+  spec.add_development_dependency('factory_bot', '~> 6.2.0')
+  spec.add_development_dependency('grpc-tools', '~> 1.42')
+  spec.add_development_dependency('rake-notes', '~> 0.2.0')
+  spec.add_development_dependency('rubocop', '~> 1.23.0')
+  spec.add_development_dependency('rubocop-rspec', '~> 2.6.0')
+  spec.add_development_dependency('simplecov', '~> 0.21.2')
+  spec.add_development_dependency('timecop', '~> 0.9.4')
+  spec.add_development_dependency('yard', '~> 0.9.27')
+  spec.metadata = {
+    'rubygems_mfa_required' => 'true'
+  }
 end

data/lib/fabric/accessors/contract.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Fabric
+  module Accessors
+    #
+    # Add accessor methods to the given class.
+    #
+    # Usage: make sure the class has a contract accessor method
+    # and then `include Fabric::Accessors::Contract`
+    #
+    module Contract
+      # @!visibility private
+      def self.included(base)
+        base.send :include, Fabric::Accessors::Network
+      end
+
+      # @!parse include Fabric::Accessors::Network
+      # @!parse include Fabric::Accessors::Gateway
+
+      #
+      # Returns the network instance
+      #
+      # @return [Fabric::Network] network
+      # @!parse attr_reader :network
+      #
+      def network
+        contract.network
+      end
+
+      #
+      # Returns the contract name
+      #
+      # @return [String] contract name
+      # @!parse attr_reader :contract_name
+      #
+      def contract_name
+        contract.contract_name
+      end
+
+      #
+      # Returns the chaincode name
+      #
+      # @return [String] chaincode name
+      # @!parse attr_reader :chaincode_name
+      #
+      def chaincode_name
+        contract.chaincode_name
+      end
+    end
+  end
+end

data/lib/fabric/accessors/gateway.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Fabric
+  module Accessors
+    #
+    # Add accessor methods to the given class.
+    #
+    # Usage: make sure the class has a gateway accessor method
+    # and then `include Fabric::Accessors::Gateway`
+    #
+    module Gateway
+      #
+      # Returns the client instance
+      #
+      # @return [Fabric::Client] client
+      # @!parse attr_reader :client
+      #
+      def client
+        gateway.client
+      end
+
+      #
+      # Returns the signer identity instance
+      #
+      # @return [Fabric::Identity] signer
+      # @!parse attr_reader :signer
+      #
+      def signer
+        gateway.signer
+      end
+    end
+  end
+end

data/lib/fabric/accessors/network.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Fabric
+  module Accessors
+    #
+    # Add accessor methods to the given class.
+    #
+    # Usage: make sure the class has a network accessor method
+    # and then `include Fabric::Accessors::Network`
+    #
+    module Network
+      # @!visibility private
+      def self.included(base)
+        base.send :include, Fabric::Accessors::Gateway
+      end
+
+      # @!parse include Fabric::Accessors::Gateway
+
+      #
+      # Returns the gateway instance
+      #
+      # @return [Fabric::Gateway] gateway
+      # @!parse attr_reader :gateway
+      #
+      def gateway
+        network.gateway
+      end
+
+      #
+      # Network name or the channel name or channel id
+      #
+      # @return [String] network name
+      # @!parse attr_reader :network_name
+      #
+      def network_name
+        network.name
+      end
+    end
+  end
+end

data/lib/fabric/client.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Fabric
+  #
+  # Gateway Client represents the connection to a Hyperledger Fabric Gateway.
+  #
+  class Client
+    attr_reader :grpc_client, :default_call_options
+
+    #
+    # Initializes a client
+    #
+    #
+    # @overload initialize(grpc_client: client, default_call_options: {}, **client_opts)
+    #   Initializes a client from a gRPC Gateway client stub
+    #   @param [Gateway::Gateway::Stub] grpc_client grpc gateway client stub
+    #   @param [Hash] default_call_options call options to use by default for different operations
+    #   @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:request_response Keyword Argument call options for
+    #     *_options default_call_options
+    #   @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:initialize Keyword arguments for **client_opts
+    #   @option default_call_options [Hash] :endorse_options default options for endorse call
+    #   @option default_call_options [Hash] :evaluate_options default options for evaluate call
+    #   @option default_call_options [Hash] :submit_options default options for submit call
+    #   @option default_call_options [Hash] :commit_status_options default options for commit_status call
+    #   @option default_call_options [Hash] :chaincode_events_options default options for chaincode_events call
+    #   @param [Hash] **client_opts client initialization options
+    # @overload initialize(host: host, creds: creds, default_call_options: {}, **client_opts)
+    #   Instantiates a new gRPC Gateway client stub from the parameters
+    #   @param [string] host hostname and port of the gateway
+    #   @param [GRPC::Core::ChannelCredentials|GRPC::Core::XdsChannelCredentials|Symbol] creds channel credentials
+    #     (usually the CA certificate)
+    #   @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:request_response Keyword Argument call options for
+    #     *_options default_call_options
+    #   @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:initialize Keyword arguments for **client_opts
+    #   @option default_call_options [Hash] :endorse_options default options for endorse call
+    #   @option default_call_options [Hash] :evaluate_options default options for evaluate call
+    #   @option default_call_options [Hash] :submit_options default options for submit call
+    #   @option default_call_options [Hash] :commit_status_options default options for commit_status call
+    #   @option default_call_options [Hash] :chaincode_events_options default options for chaincode_events call
+    #   @param [Hash] **client_opts client initialization options
+    #
+    def initialize(grpc_client: nil, host: nil, creds: nil, default_call_options: {}, **client_opts)
+      if grpc_client
+        init_stub grpc_client
+      elsif host && creds
+        init_grpc_args(host, creds, **client_opts)
+      else
+        raise InvalidArgument, 'Must pass a Gateway::Gateway::Stub or <host>, <creds>, <client_opts>'
+      end
+      init_call_options(default_call_options)
+    end
+
+    #
+    # Submits an evaluate_request to the gateway to be evaluted.
+    #
+    # @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:request_response Call options for options parameter
+    # @param [Gateway::EvaluateRequest] evaluate_request
+    # @param [Hash] options gRPC call options (merged with default_call_options from initializer)
+    #
+    # @return [Gateway::EvaluateResponse] evaluate_response
+    #
+    def evaluate(evaluate_request, options = {})
+      @grpc_client.evaluate(evaluate_request, @default_call_options[:evaluate_options].merge(options))
+    end
+
+    #
+    # Submits an endorse_request to the gateway to be evaluted.
+    #
+    # @param [Gateway::EndorseRequest] endorse_request
+    # @param [Hash] options gRPC call options (merged with default options) @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:request_response
+    #
+    # @return [Gateway::EndorseResponse] endorse_response
+    #
+    def endorse(endorse_request, options = {})
+      @grpc_client.endorse(endorse_request, @default_call_options[:endorse_options].merge(options))
+    end
+
+    #
+    # Submits an submit_request to the gateway to be evaluted.
+    #
+    # @param [Gateway::SubmitRequest] submit_request
+    # @param [Hash] options gRPC call options (merged with default options) @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:request_response
+    #
+    # @return [Gateway::SubmitResponse] submit_response
+    #
+    def submit(submit_request, options = {})
+      @grpc_client.submit(submit_request, @default_call_options[:submit_options].merge(options))
+    end
+
+    #
+    # Submits an commit_status_request to the gateway to be evaluted.
+    #
+    # @param [Gateway::CommitStatusRequest] commit_status_request
+    # @param [Hash] options gRPC call options (merged with default options) @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:request_response
+    #
+    # Returns an enum or if you pass a block, use the block.
+    # @return [Gateway::CommitStatusResponse] commit_status_response
+    #
+    def commit_status(commit_status_request, options = {})
+      @grpc_client.commit_status(commit_status_request, @default_call_options[:commit_status_options].merge(options))
+    end
+
+    #
+    # Subscribe to chaincode events
+    #
+    # @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:server_streamer GRPC::ClientStub#server_streamer
+    #   - gRPC Underlying Call Reference
+    #
+    #
+    # @overload chaincode_events(chaincode_events_request)
+    #   @example Utilizing Blocking Enumerator
+    #     call = client.chaincode_events(chaincode_events_request)
+    #     call.each do |event|
+    #       pp event
+    #     end
+    #   @param [Gateway::ChaincodeEventsRequest] chaincode_events_request
+    #   @param [Hash] options gRPC call options (merged with default options)
+    #   @return [Enumerator] enumerator with Gateway::ChaincodeEventsResponse objects
+    # @overload chaincode_events(chaincode_events_request)
+    #   @example Utilizing a blocking block
+    #     client.chaincode_events(chaincode_events_request) do |event|
+    #       pp event
+    #     end
+    #   @param [Gateway::ChaincodeEventsRequest] chaincode_events_request
+    #   @param [Hash] options gRPC call options (merged with default options)
+    #   @yield [event] Blocking call that yields Gateway::ChaincodeEventsResponse objects when received from the server
+    #   @yieldparam event [Gateway::ChaincodeEventsResponse] chaincode event
+    #   @return [nil]
+    # @overload chaincode_events(chaincode_events_request, {return_op: true})
+    #   @example Utilizing an operation control object and a enumerator
+    #     op = client.chaincode_events(chaincode_events_request, {return_op: true})
+    #
+    #     t = Thread.new do
+    #       call = op.execute
+    #       call.each do |event|
+    #         pp event
+    #       end
+    #     end
+    #
+    #     op.status
+    #     op.cancelled?
+    #     op.cancel
+    #   @param [Gateway::ChaincodeEventsRequest] chaincode_events_request
+    #   @param [Hash] options gRPC call options (merged with default options)
+    #   @return [GRPC::ActiveCall::Operation]
+    # @overload chaincode_events(chaincode_events_request, {return_op: true})
+    #   @example Utilizing an operation control object and a block
+    #     op = client.chaincode_events(chaincode_events_request, {return_op: true}) do |event|
+    #       pp event
+    #     end
+    #
+    #     t = Thread.new do
+    #       call = op.execute
+    #     end
+    #
+    #     op.status
+    #     op.cancelled?
+    #     op.cancel
+    #   @param [Gateway::ChaincodeEventsRequest] chaincode_events_request
+    #   @param [Hash] options gRPC call options (merged with default options)
+    #   @yield [event] Blocking call that yields Gateway::ChaincodeEventsResponse objects when received from the server
+    #   @yieldparam event [Gateway::ChaincodeEventsResponse] chaincode event
+    #   @return [GRPC::ActiveCall::Operation]
+    #
+    def chaincode_events(chaincode_events_request, options = {}, &block)
+      @grpc_client.chaincode_events(chaincode_events_request,
+                                    @default_call_options[:chaincode_events_options].merge(options), &block)
+    end
+
+    private
+
+    def init_stub(stub)
+      unless stub.is_a? ::Gateway::Gateway::Stub
+        raise InvalidArgument, 'Must pass a Gateway::Gateway::Stub or <host>, <creds>, <client_opts>'
+      end
+
+      @grpc_client = stub
+    end
+
+    def init_grpc_args(host, creds, **client_opts)
+      unless creds.is_a?(GRPC::Core::ChannelCredentials) ||
+             creds.is_a?(GRPC::Core::XdsChannelCredentials) ||
+             creds.is_a?(Symbol)
+        raise InvalidArgument, 'creds is not a ChannelCredentials, XdsChannelCredentials, or Symbol'
+      end
+
+      @grpc_client = ::Gateway::Gateway::Stub.new(host, creds, **client_opts)
+    end
+
+    def init_call_options(call_options)
+      @default_call_options = call_options
+      @default_call_options[:endorse_options] ||= {}
+      @default_call_options[:evaluate_options] ||= {}
+      @default_call_options[:submit_options] ||= {}
+      @default_call_options[:commit_status_options] ||= {}
+      @default_call_options[:chaincode_events_options] ||= {}
+    end
+  end
+end

data/lib/fabric/constants.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Fabric
+  module Constants
+    ## Variables
+    CHANNEL_HEADER_VERSION = 1
+  end
+end

data/lib/fabric/contract.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Fabric
+  #
+  # Contract represents a smart contract, and allows applications to:
+  #
+  # - Evaluate transactions that query state from the ledger using the EvaluateTransaction() method.
+  #
+  # - Submit transactions that store state to the ledger using the SubmitTransaction() method.
+  #
+  # For more complex transaction invocations, such as including transient data, transactions can be evaluated or
+  # submitted using the Evaluate() or Submit() methods respectively. The result of a submitted transaction can be
+  # accessed prior to its commit to the ledger using SubmitAsync().
+  #
+  # By default, proposal, transaction and commit status messages will be signed using the signing implementation
+  # specified when connecting the Gateway. In cases where an external client holds the signing credentials, a signing
+  # implementation can be omitted when connecting the Gateway and off-line signing can be carried out by:
+  #
+  # 1. Returning the serialized proposal, transaction or commit status   along with its digest to the client for
+  # them to generate a signature.
+  #
+  # 2. With the serialized message and signature received from the client to create a signed proposal, transaction or
+  # commit using the Gateway's NewSignedProposal(), NewSignedTransaction() or NewSignedCommit() methods respectively.
+  #
+  class Contract
+    attr_reader :network, :chaincode_name, :contract_name
+
+    # @!parse include Fabric::Accessors::Network
+    # @!parse include Fabric::Accessors::Gateway
+    include Fabric::Accessors::Network
+
+    def initialize(network, chaincode_name, contract_name = '')
+      @network = network
+      @chaincode_name = chaincode_name
+      @contract_name = contract_name
+    end
+
+    #
+    # Evaluate a transaction function and return its results. A transaction proposal will be evaluated on endorsing
+    # peers but the transaction will not be sent to the ordering service and so will not be committed to the ledger.
+    # This can be used for querying the world state.
+    #
+    # @param [String] transaction_name
+    # @param [Array] arguments array of arguments to pass to the transaction
+    #
+    # @return [String] raw payload of the transaction response
+    #
+    def evaluate_transaction(transaction_name, arguments = [])
+      evaluate(transaction_name, { arguments: arguments })
+    end
+
+    #
+    # Submit a transaction to the ledger and return its result only after it is committed to the ledger. The
+    # transaction function will be evaluated on endorsing peers and then submitted to the ordering service to be
+    # committed to the ledger.
+    #
+    #
+    # @param [String] transaction_name
+    # @param [Array] arguments array of arguments to pass to the transaction
+    #
+    # @return [String] raw payload of the transaction response
+    #
+    def submit_transaction(transaction_name, arguments = [])
+      submit(transaction_name, { arguments: arguments })
+    end
+
+    #
+    # Evaluate a transaction function and return its result. This method provides greater control over the transaction
+    # proposal content and the endorsing peers on which it is evaluated. This allows transaction functions to be
+    # evaluated where the proposal must include transient data, or that will access ledger data with key-based
+    # endorsement policies.
+    #
+    # @param [String] transaction_name
+    # @param [Hash] proposal_options
+    # @option proposal_options [Array] :arguments array of arguments to pass to the transaction
+    # @option proposal_options [Hash] :transient_data Private data passed to the transaction function but not recorded
+    #                                                 on the ledger.
+    # @option proposal_options [Array] :endorsing_organizations Specifies the set of organizations that will attempt to
+    #                                                           endorse the proposal.
+    #
+    # @return [String] Raw evaluation response payload
+    #
+    def evaluate(transaction_name, proposal_options = {})
+      new_proposal(transaction_name, **proposal_options).evaluate
+    end
+
+    #
+    # Submit a transaction to the ledger and return its result only after it is committed to the ledger. The
+    # transaction function will be evaluated on endorsing peers and then submitted to the ordering service to be
+    # committed to the ledger.
+    #
+    # @param [String] transaction_name
+    # @param [Hash] proposal_options
+    # @option proposal_options [Array] :arguments array of arguments to pass to the transaction
+    # @option proposal_options [Hash] :transient_data Private data passed to the transaction function but not recorded
+    #                                                 on the ledger.
+    # @option proposal_options [Array] :endorsing_organizations Specifies the set of organizations that will attempt to
+    #                                                           endorse the proposal.
+    #
+    # @return [String] Raw evaluation response payload
+    #
+    def submit(transaction_name, proposal_options = {})
+      transaction = new_proposal(transaction_name, **proposal_options).endorse
+      transaction.submit
+
+      transaction.result
+    end
+
+    #
+    # @todo unimplemented, not sure if this can be implemented because
+    #   the official grpc ruby client does not support non-blocking async
+    #   calls (https://github.com/grpc/grpc/issues/10973)
+    #
+    # not 100% sure if grpc support is necessary for this.
+    #
+    def submit_async
+      raise NotYetImplemented
+    end
+
+    #
+    # Get chaincode events emitted by transaction functions of the chaincode.
+    #
+    # @see Fabric::Client#chaincode_events Fabric::Client#chaincode_events - explanation of the different return types
+    #   and example usage.
+    # @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:server_streamer Call options for options parameter
+    #
+    # @param [Integer] start_block Block number at which to start reading chaincode events.
+    # @param [Hash] call_options gRPC call options (merged with default_call_options from initializer)
+    # @yield [chaincode_event] loops through the chaincode events
+    # @yieldparam [Gateway::ChaincodeEventsResponse] chaincode_event the chaincode event
+    #
+    # @return [Enumerator|GRPC::ActiveCall::Operation|nil] Dependent on parameters passed;
+    #   please see Fabric::Client#get_chaincode_events
+    #
+    def chaincode_events(start_block: nil, call_options: {}, &block)
+      network.chaincode_events(
+        self,
+        start_block: start_block,
+        call_options: call_options,
+        &block
+      )
+    end
+
+    #
+    # Creates a transaction proposal that can be evaluated or endorsed. Supports off-line signing flow.
+    #
+    # @param [String] transaction_name transaction name (first argument unshifted into the argument array)
+    # @param [Array<String>] arguments array of arguments to pass to the transaction
+    # @param [Hash] transient_data Private data passed to the transaction function but not recorded on the ledger.
+    # @param [Array] endorsing_organizations Specifies the set of organizations that will attempt to endorse the
+    #                                        proposal.
+    #
+    # @return [Fabric::Proposal] signed unexecuted proposal
+    #
+    def new_proposal(transaction_name, arguments: [], transient_data: {}, endorsing_organizations: [])
+      proposed_transaction = ProposedTransaction.new(
+        self,
+        qualified_transaction_name(transaction_name),
+        arguments: arguments,
+        transient_data: transient_data,
+        endorsing_organizations: endorsing_organizations
+      )
+      Proposal.new(proposed_transaction)
+    end
+
+    #
+    # Generates the qualified transaction name for the contract. (prepends the contract name to the transaction name if
+    # contract name is set)
+    #
+    # @param [string] transaction_name
+    #
+    # @return [string] qualified transaction name
+    #
+    def qualified_transaction_name(transaction_name)
+      contract_name.nil? || contract_name.empty? ? transaction_name : "#{contract_name}:#{transaction_name}"
+    end
+  end
+end