fabric-gateway 0.0.1 → 0.3.0

data/lib/common/common_pb.rb

@@ -0,0 +1,113 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: common/common.proto
+
+require 'google/protobuf/timestamp_pb'
+require 'google/protobuf'
+
+Google::Protobuf::DescriptorPool.generated_pool.build do
+  add_file("common/common.proto", :syntax => :proto3) do
+    add_message "common.LastConfig" do
+      optional :index, :uint64, 1
+    end
+    add_message "common.Metadata" do
+      optional :value, :bytes, 1
+      repeated :signatures, :message, 2, "common.MetadataSignature"
+    end
+    add_message "common.MetadataSignature" do
+      optional :signature_header, :bytes, 1
+      optional :signature, :bytes, 2
+    end
+    add_message "common.Header" do
+      optional :channel_header, :bytes, 1
+      optional :signature_header, :bytes, 2
+    end
+    add_message "common.ChannelHeader" do
+      optional :type, :int32, 1
+      optional :version, :int32, 2
+      optional :timestamp, :message, 3, "google.protobuf.Timestamp"
+      optional :channel_id, :string, 4
+      optional :tx_id, :string, 5
+      optional :epoch, :uint64, 6
+      optional :extension, :bytes, 7
+      optional :tls_cert_hash, :bytes, 8
+    end
+    add_message "common.SignatureHeader" do
+      optional :creator, :bytes, 1
+      optional :nonce, :bytes, 2
+    end
+    add_message "common.Payload" do
+      optional :header, :message, 1, "common.Header"
+      optional :data, :bytes, 2
+    end
+    add_message "common.Envelope" do
+      optional :payload, :bytes, 1
+      optional :signature, :bytes, 2
+    end
+    add_message "common.Block" do
+      optional :header, :message, 1, "common.BlockHeader"
+      optional :data, :message, 2, "common.BlockData"
+      optional :metadata, :message, 3, "common.BlockMetadata"
+    end
+    add_message "common.BlockHeader" do
+      optional :number, :uint64, 1
+      optional :previous_hash, :bytes, 2
+      optional :data_hash, :bytes, 3
+    end
+    add_message "common.BlockData" do
+      repeated :data, :bytes, 1
+    end
+    add_message "common.BlockMetadata" do
+      repeated :metadata, :bytes, 1
+    end
+    add_message "common.OrdererBlockMetadata" do
+      optional :last_config, :message, 1, "common.LastConfig"
+      optional :consenter_metadata, :bytes, 2
+    end
+    add_enum "common.Status" do
+      value :UNKNOWN, 0
+      value :SUCCESS, 200
+      value :BAD_REQUEST, 400
+      value :FORBIDDEN, 403
+      value :NOT_FOUND, 404
+      value :REQUEST_ENTITY_TOO_LARGE, 413
+      value :INTERNAL_SERVER_ERROR, 500
+      value :NOT_IMPLEMENTED, 501
+      value :SERVICE_UNAVAILABLE, 503
+    end
+    add_enum "common.HeaderType" do
+      value :MESSAGE, 0
+      value :CONFIG, 1
+      value :CONFIG_UPDATE, 2
+      value :ENDORSER_TRANSACTION, 3
+      value :ORDERER_TRANSACTION, 4
+      value :DELIVER_SEEK_INFO, 5
+      value :CHAINCODE_PACKAGE, 6
+    end
+    add_enum "common.BlockMetadataIndex" do
+      value :SIGNATURES, 0
+      value :LAST_CONFIG, 1
+      value :TRANSACTIONS_FILTER, 2
+      value :ORDERER, 3
+      value :COMMIT_HASH, 4
+    end
+  end
+end
+
+module Common
+  LastConfig = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.LastConfig").msgclass
+  Metadata = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.Metadata").msgclass
+  MetadataSignature = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.MetadataSignature").msgclass
+  Header = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.Header").msgclass
+  ChannelHeader = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.ChannelHeader").msgclass
+  SignatureHeader = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.SignatureHeader").msgclass
+  Payload = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.Payload").msgclass
+  Envelope = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.Envelope").msgclass
+  Block = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.Block").msgclass
+  BlockHeader = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.BlockHeader").msgclass
+  BlockData = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.BlockData").msgclass
+  BlockMetadata = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.BlockMetadata").msgclass
+  OrdererBlockMetadata = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.OrdererBlockMetadata").msgclass
+  Status = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.Status").enummodule
+  HeaderType = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.HeaderType").enummodule
+  BlockMetadataIndex = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.BlockMetadataIndex").enummodule
+end

data/lib/common/policies_pb.rb

@@ -0,0 +1,61 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: common/policies.proto
+
+require 'msp/msp_principal_pb'
+require 'google/protobuf'
+
+Google::Protobuf::DescriptorPool.generated_pool.build do
+  add_file("common/policies.proto", :syntax => :proto3) do
+    add_message "common.Policy" do
+      optional :type, :int32, 1
+      optional :value, :bytes, 2
+    end
+    add_enum "common.Policy.PolicyType" do
+      value :UNKNOWN, 0
+      value :SIGNATURE, 1
+      value :MSP, 2
+      value :IMPLICIT_META, 3
+    end
+    add_message "common.SignaturePolicyEnvelope" do
+      optional :version, :int32, 1
+      optional :rule, :message, 2, "common.SignaturePolicy"
+      repeated :identities, :message, 3, "common.MSPPrincipal"
+    end
+    add_message "common.SignaturePolicy" do
+      oneof :Type do
+        optional :signed_by, :int32, 1
+        optional :n_out_of, :message, 2, "common.SignaturePolicy.NOutOf"
+      end
+    end
+    add_message "common.SignaturePolicy.NOutOf" do
+      optional :n, :int32, 1
+      repeated :rules, :message, 2, "common.SignaturePolicy"
+    end
+    add_message "common.ImplicitMetaPolicy" do
+      optional :sub_policy, :string, 1
+      optional :rule, :enum, 2, "common.ImplicitMetaPolicy.Rule"
+    end
+    add_enum "common.ImplicitMetaPolicy.Rule" do
+      value :ANY, 0
+      value :ALL, 1
+      value :MAJORITY, 2
+    end
+    add_message "common.ApplicationPolicy" do
+      oneof :Type do
+        optional :signature_policy, :message, 1, "common.SignaturePolicyEnvelope"
+        optional :channel_config_policy_reference, :string, 2
+      end
+    end
+  end
+end
+
+module Common
+  Policy = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.Policy").msgclass
+  Policy::PolicyType = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.Policy.PolicyType").enummodule
+  SignaturePolicyEnvelope = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.SignaturePolicyEnvelope").msgclass
+  SignaturePolicy = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.SignaturePolicy").msgclass
+  SignaturePolicy::NOutOf = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.SignaturePolicy.NOutOf").msgclass
+  ImplicitMetaPolicy = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.ImplicitMetaPolicy").msgclass
+  ImplicitMetaPolicy::Rule = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.ImplicitMetaPolicy.Rule").enummodule
+  ApplicationPolicy = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("common.ApplicationPolicy").msgclass
+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,146 @@
+# 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.
+    #
+    # @param [Gateway::EvaluateRequest] evaluate_request
+    # @param [Hash] options gRPC call options (merged with default options) @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:request_response
+    #
+    # @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
+    #
+    # @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
+    #
+    # @note This function has never been utilized or tested. This function is probably wrong, missing a block.
+    # @todo add testing!
+    #
+    # @param [Gateway::ChaincodeEventsRequest] chaincode_events_request
+    # @param [Hash] options gRPC call options (merged with default options) @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:server_streamer
+    #
+    # @return [Gateway::ChaincodeEventsResponse] commit_status_response (probably wrong, this is a stream.)
+    #
+    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,154 @@
+# 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
+
+    #
+    # 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