fabric-gateway 0.2.0 → 0.4.1

data/lib/fabric/entities/transaction.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module Fabric
+  #
+  # Represents an endorsed transaction that can be submitted to the orderer for commit to the ledger,
+  # query the transaction results and its commit status.
+  #
+  class Transaction
+    attr_reader :network
+
+    include Fabric::Accessors::Network
+
+    # @return [Gateway::PreparedTransaction] Prepared Transaction
+    attr_reader :prepared_transaction
+
+    # @return [Fabric::Envelope]
+    attr_reader :envelope
+
+    #
+    # Creates a new Transaction instance.
+    #
+    # @param [Fabric::Network] network
+    # @param [Gateway::PreparedTransaction] prepared_transaction
+    #
+    def initialize(network, prepared_transaction)
+      @network = network
+      @prepared_transaction = prepared_transaction
+      @envelope = Envelope.new(prepared_transaction.envelope)
+    end
+
+    #
+    # Get the transaction result. This is obtained during the endorsement process when the transaction proposal is
+    # run on endorsing peers.
+    #
+    # @param [boolean] check_status set to true to raise exception if transaction has not yet been committed
+    #
+    # @return [String] Raw transaction result
+    #
+    def result(check_status: true)
+      raise Fabric::CommitError, status if check_status && !status.successful
+
+      envelope.result
+    end
+
+    #
+    # Returns the transaction ID from the prepared transaction.
+    #
+    # @return [String] transaction_id
+    #
+    def transaction_id
+      prepared_transaction.transaction_id
+    end
+
+    #
+    # Submit the transaction to the orderer to be committed to the ledger.
+    #
+    # @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:request_response
+    #
+    # @param [Hash] options gRPC call options
+    #
+    # @return [Fabric::Transaction] self
+    def submit(options = {})
+      sign_submit_request
+
+      client.submit(new_submit_request, options)
+
+      self
+    end
+
+    #
+    # Sign the transaction envelope.
+    #
+    # @return [void]
+    def sign_submit_request
+      return if submit_request_signed?
+
+      signature = signer.sign(envelope.payload_bytes)
+      self.submit_request_signature = signature
+    end
+
+    #
+    # Returns true if the transaction envelope has been signed.
+    #
+    # @return [Boolean] true if signed; false otherwise
+    #
+    def submit_request_signed?
+      @envelope.signed?
+    end
+
+    #
+    # Digest to be signed to support offline signing of the submit request
+    #
+    # @return [String] digest of the submit request
+    #
+    def submit_request_digest
+      envelope.payload_digest
+    end
+
+    #
+    # Sets the submit request signature. This is used to support offline signing of the submit request.
+    #
+    # @param [String] signature
+    #
+    # @return [void]
+    #
+    def submit_request_signature=(signature)
+      envelope.signature = signature
+    end
+
+    #
+    # Get status of the committed transaction. If the transaction has not yet committed, this method blocks until the
+    # commit occurs. If status is already queried, this returns status from cache and does not make additional queries.
+    #
+    # @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:request_response
+    #
+    # @param [Hash] options gRPC call options
+    #
+    # @return [Fabric::Status] status of the committed transaction
+    #
+    def status(options = {})
+      @status ||= query_status(options)
+    end
+
+    #
+    # Digest to be signed to support offline signing of the commit status request
+    #
+    # @return [String] digest of the commit status request
+    #
+    def status_request_digest
+      Fabric.crypto_suite.digest(signed_commit_status_request.request)
+    end
+
+    #
+    # Sets the status request signature. This is used to support offline signing of the commit status request.
+    #
+    # @param [String] signature
+    #
+    # @return [void]
+    #
+    def status_request_signature=(signature)
+      signed_commit_status_request.signature = signature
+    end
+
+    #
+    # Returns true if the signed commit status request has been signed.
+    #
+    # @return [Boolean] true if signed; false otherwise
+    #
+    def status_request_signed?
+      !signed_commit_status_request.signature.empty?
+    end
+
+    #
+    # Sign the signed commit status request
+    #
+    # @return [Fabric::Transaction] self
+    #
+    def sign_status_request
+      return if status_request_signed?
+
+      signature = signer.sign(signed_commit_status_request.request)
+      signed_commit_status_request.signature = signature
+
+      self
+    end
+
+    #
+    # Returns the current instance of the signed commit status request. Necessary so we can keep the state of the
+    # signature in the transaction object.
+    #
+    # @return [Gateway::SignedCommitStatusRequest] signed commit status request
+    #
+    def signed_commit_status_request
+      @signed_commit_status_request ||= new_signed_commit_status_request
+    end
+
+    private
+
+    #
+    # Actual status query call used by status method.
+    #
+    # @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:request_response
+    #
+    # @param [Hash] options gRPC call options
+    #
+    # @return [Fabric::Status] status of the committed transaction
+    #
+    def query_status(options = {})
+      sign_status_request
+
+      commit_status_response = client.commit_status(signed_commit_status_request, options)
+      new_status(commit_status_response)
+    end
+
+    #
+    # Generates a new signed commit status request
+    #
+    # @return [Gateway::SignedCommitStatusRequest] signed commit status request protobuf message
+    #
+    def new_signed_commit_status_request
+      ::Gateway::SignedCommitStatusRequest.new(
+        request: new_commit_status_request.to_proto
+      )
+    end
+
+    #
+    # Generates a new commit status request
+    #
+    # @return [Gateway::CommitStatusRequest] commit status request protobuf message
+    #
+    def new_commit_status_request
+      ::Gateway::CommitStatusRequest.new(
+        channel_id: network_name,
+        transaction_id: transaction_id,
+        identity: signer.to_proto
+      )
+    end
+
+    #
+    # Generates a new submit request.
+    #
+    # @return [Gateway::SubmitRequest] submit request protobuf message
+    #
+    def new_submit_request
+      ::Gateway::SubmitRequest.new(
+        transaction_id: transaction_id,
+        channel_id: network_name,
+        prepared_transaction: envelope.envelope
+      )
+    end
+
+    #
+    # New Status from CommitStatusResponse
+    #
+    # @param [Gateway::CommitStatusResponse] response commit status response
+    #
+    # @return [Fabric::Status] transaction status
+    #
+    def new_status(response)
+      Fabric::Status.new(
+        transaction_id,
+        response.block_number,
+        Fabric::Status::TRANSACTION_STATUSES[response.result]
+      )
+    end
+  end
+end

data/lib/fabric/network.rb

@@ -11,19 +11,14 @@ module Fabric
   class Network
     attr_reader :gateway, :name
 
+    # @!parse include Fabric::Accessors::Gateway
+    include Fabric::Accessors::Gateway
+
     def initialize(gateway, name)
       @gateway = gateway
       @name = name
     end
 
-    def client
-      gateway.client
-    end
-
-    def signer
-      gateway.signer
-    end
-
     #
     # Creates a new contract instance
     #
@@ -37,25 +32,39 @@ module Fabric
     end
 
     #
-    # @TODO: original SDK has getChaincodeEvents and newChaincodeEventsRequest methods
-    # @see https://github.com/hyperledger/fabric-gateway/blob/08118cf0a792898925d0b2710b0a9e7c5ec23228/node/src/network.ts
-    # @see https://github.com/hyperledger/fabric-gateway/blob/main/pkg/client/network.go
+    # Get chaincode events emitted by transaction functions of a specific 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
     #
-    # @return [?] ?
+    # @param [Fabric::Contract] contract the chaincode to listen for events on
+    # @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 chaincode_event [Gateway::ChaincodeEventsResponse] the chaincode event
     #
-    def new_chaincode_events
-      raise NotYetImplemented
+    # @return [Enumerator|GRPC::ActiveCall::Operation|nil] Dependent on parameters passed;
+    #   please see Fabric::Client#get_chaincode_events
+    #
+    def chaincode_events(contract, start_block: nil, call_options: {}, &block)
+      new_chaincode_events_request(contract, start_block: start_block).get_events(call_options, &block)
     end
 
     #
-    # @TODO: original SDK has getChaincodeEvents and newChaincodeEventsRequest methods
-    # @see https://github.com/hyperledger/fabric-gateway/blob/08118cf0a792898925d0b2710b0a9e7c5ec23228/node/src/network.ts
-    # @see https://github.com/hyperledger/fabric-gateway/blob/main/pkg/client/network.go
+    # Create a request to receive chaincode events emitted by transaction functions of a specific chaincode. Supports
+    # off-line signing flow.
+    #
+    # @note I'm lying. I just copy and pasted the description from the node SDK. Offline signing should work, but it has
+    #   not been explicitly tested.
+    # @todo Test off-line signing flow.
     #
-    # @return [?] ?
+    # @param [Fabric::Contract] contract the chaincode to listen for events on
+    # @param [Integer] start_block Block number at which to start reading chaincode events.
+    # @return [Fabric::ChaincodeEventsRequest] Encapsulated ChaincodeEventsRequest
     #
-    def new_chaincode_events_request
-      raise NotImplementedError
+    def new_chaincode_events_request(contract, start_block: nil)
+      ChaincodeEventsRequest.new(contract, start_block: start_block)
     end
   end
 end

data/lib/fabric/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fabric
-  VERSION = '0.2.0'
+  VERSION = '0.4.1'
 end

data/lib/fabric.rb

@@ -1,19 +1,28 @@
 # frozen_string_literal: true
 
+require 'gateway/gateway_pb'
+require 'gateway/gateway_services_pb'
+
+require 'fabric/accessors/gateway'
+require 'fabric/accessors/network'
+require 'fabric/accessors/contract'
+
+require 'fabric/entities/envelope'
+require 'fabric/entities/identity'
+require 'fabric/entities/proposal'
+require 'fabric/entities/proposed_transaction'
+require 'fabric/entities/status'
+require 'fabric/entities/transaction'
+require 'fabric/entities/chaincode_events_requests'
+
 require 'fabric/constants'
 require 'fabric/contract'
 require 'fabric/client'
 require 'fabric/ec_crypto_suite'
 require 'fabric/gateway'
-require 'fabric/identity'
 require 'fabric/network'
-require 'fabric/proposal'
-require 'fabric/proposed_transaction'
 require 'fabric/version'
 
-require 'gateway/gateway_pb'
-require 'gateway/gateway_services_pb'
-
 #
 # Hyperledger Fabric Gateway SDK
 #
@@ -25,14 +34,20 @@ module Fabric
   #
   # CommitError
   #
-  # @TODO: TEST ME!
+  # TODO: Add RSpec Tests for CommitError
+  # @todo TEST ME!
   #
   class CommitError < Error
     attr_reader :code, :transaction_id
 
+    #
+    # Creates a transaction commit error from the status
+    #
+    # @param [Fabric::Status] status transaction status
+    #
     def initialize(status)
-      super("Transaction #{status.transaction_id} failed to commit with status code #{status.code} -" +
-        Protos::TxValidationCode.lookup(status.code).to_s)
+      super("Transaction #{status.transaction_id} failed to commit with status code #{status.code} - " +
+        Status::TRANSACTION_STATUSES.key(status.code).to_s)
       @code = code
       @transaction_id = status.transaction_id
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fabric-gateway
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Jonathan Chan
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-12-29 00:00:00.000000000 Z
+date: 2022-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-protobuf
@@ -72,14 +72,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.42'
+        version: 1.46.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.42'
+        version: 1.46.2
+- !ruby/object:Gem::Dependency
+  name: rake-notes
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -136,8 +150,21 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.9.4
-description: 'Hyperledger Fabric Gateway gRPC SDK generated directly from protos found
-  at: https://github.com/hyperledger/fabric-protos.'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.27
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.27
+description: Ruby port of the Hyperledger Fabric Gateway SDK
 email:
 - jonathan.chan@ethicalidentity.com
 executables: []
@@ -145,8 +172,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".editorconfig"
+- ".github/workflows/codeql-analysis.yml"
 - ".github/workflows/rspec.yml"
 - ".github/workflows/rubocop.yml"
+- ".github/workflows/todo.yml"
+- ".github/workflows/yardoc.yml"
 - ".gitignore"
 - ".gitmodules"
 - ".rspec"
@@ -154,6 +184,7 @@ files:
 - ".ruby-version"
 - ".travis.yml"
 - ".vscode/settings.json"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -171,15 +202,22 @@ files:
 - lib/common/policies_pb.rb
 - lib/fabric.rb
 - lib/fabric/.DS_Store
+- lib/fabric/accessors/contract.rb
+- lib/fabric/accessors/gateway.rb
+- lib/fabric/accessors/network.rb
 - lib/fabric/client.rb
 - lib/fabric/constants.rb
 - lib/fabric/contract.rb
 - lib/fabric/ec_crypto_suite.rb
+- lib/fabric/entities/chaincode_events_requests.rb
+- lib/fabric/entities/envelope.rb
+- lib/fabric/entities/identity.rb
+- lib/fabric/entities/proposal.rb
+- lib/fabric/entities/proposed_transaction.rb
+- lib/fabric/entities/status.rb
+- lib/fabric/entities/transaction.rb
 - lib/fabric/gateway.rb
-- lib/fabric/identity.rb
 - lib/fabric/network.rb
-- lib/fabric/proposal.rb
-- lib/fabric/proposed_transaction.rb
 - lib/fabric/version.rb
 - lib/gateway/gateway_pb.rb
 - lib/gateway/gateway_services_pb.rb
@@ -217,5 +255,5 @@ requirements: []
 rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
-summary: Hyperledger Fabric Gateway gRPC SDK
+summary: Hyperledger Fabric Gateway SDK
 test_files: []