fabric-gateway 0.0.2 → 0.4.0

data/lib/fabric/entities/proposal.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Fabric
+  #
+  # Proposal represents a transaction proposal that can be sent to peers for endorsement or evaluated as a query.
+  #
+  # Combined ProposalBuilder with Proposal. Utilizing instance variables and functions in proposal seem adaquate enough
+  # to fully create the proposal. ProposalBuilder did not seem like a native ruby design pattern.
+  class Proposal
+    attr_reader :proposed_transaction
+
+    #
+    # Instantiates a new Proposal
+    #
+    # @param [Fabric::ProposedTransaction] proposed_transaction ProposedTransaction container class
+    #
+    def initialize(proposed_transaction)
+      @proposed_transaction = proposed_transaction
+    end
+
+    def contract
+      @proposed_transaction.contract
+    end
+
+    include Fabric::Accessors::Contract
+
+    def transaction_id
+      proposed_transaction.transaction_id
+    end
+
+    #
+    # Returns the proposal message as a protobuf Message object.
+    #
+    # @return [Protos::Proposal|nil] Proposal message
+    #
+    def proposal
+      proposed_transaction.proposal
+    end
+
+    #
+    # Returns the signed proposal
+    #
+    # <rant>
+    # Fabric message naming scheme is a mess:
+    # ProposedTransaction has a Proposal which is a SignedProposal
+    #               which has a Proposal which is a Proposal
+    # so.... which proposal do you want to access? Adding this function for clarity
+    # </rant>
+    #
+    # @return [Protos::SignedProposal|nil] SignedProposal message
+    #
+    def signed_proposal
+      proposed_transaction.proposed_transaction.proposal
+    end
+
+    #
+    # Serialized bytes of the proposal message in proto3 format.
+    #
+    # @return [String] Binary representation of the proposal message.
+    #
+    def to_proto
+      proposed_transaction.to_proto
+    end
+
+    #
+    # Proposal digest which can be utilized for offline signing.
+    # If signing offline, call signature= to set signature once
+    # computed.
+    #
+    # @return [String] raw binary digest of the proposal message.
+    #
+    def digest
+      Fabric.crypto_suite.digest(proposal.to_proto)
+    end
+
+    #
+    # Sets the signature of the signed proposal in the proposed transaction
+    #
+    # @param [String] signature raw byte string signature of the proposal message
+    #                 (should be the signature of the proposed message digest)
+    #
+    def signature=(signature)
+      proposed_transaction.signed_proposal.signature = signature
+    end
+
+    #
+    # Returns the signed proposal signature
+    #
+    # @return [String] Raw byte string signature
+    #
+    def signature
+      proposed_transaction.signed_proposal.signature
+    end
+
+    #
+    # Returns true if the signed proposal has a signature
+    #
+    # @return [Boolean] true|false
+    #
+    def signed?
+      # signature cannot be nil because google protobuf won't let it
+      !proposed_transaction.signed_proposal.signature.empty?
+    end
+
+    #
+    # Utilizes the signer to sign the proposal message if it has not been signed yet.
+    #
+    def sign
+      return if signed?
+
+      self.signature = signer.sign proposal.to_proto
+    end
+
+    #
+    # Evaluate the transaction proposal and obtain its result, without updating the ledger. This runs the transaction
+    # on a peer to obtain a transaction result, but does not submit the endorsed transaction to the orderer to be
+    # committed to the ledger.
+    #
+    # @param [Hash] options gRPC call options @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:request_response
+    #
+    # @return [String] The result returned by the transaction function
+    #
+    def evaluate(options = {})
+      sign
+
+      evaluate_response = client.evaluate(new_evaluate_request, options)
+      evaluate_response.result.payload
+    end
+
+    #
+    # Obtain endorsement for the transaction proposal from sufficient peers to allow it to be committed to the ledger.
+    #
+    # @param [Hash] options gRPC call options @see https://www.rubydoc.info/gems/grpc/GRPC%2FClientStub:request_response
+    #
+    # @return [Fabric::Transaction] An endorsed transaction that can be submitted to the ledger.
+    #
+    def endorse(options = {})
+      sign
+      endorse_response = client.endorse(new_endorse_request, options)
+
+      raise Fabric::Error, 'Missing transaction envelope' if endorse_response.prepared_transaction.nil?
+
+      prepared_transaction = new_prepared_transaction(endorse_response.prepared_transaction)
+
+      Fabric::Transaction.new(network, prepared_transaction)
+    end
+
+    #
+    # Generates an evaluate request from this proposal.
+    #
+    # @return [Gateway::EvaluateRequest] evaluation request with the current proposal
+    #
+    def new_evaluate_request
+      ::Gateway::EvaluateRequest.new(
+        channel_id: network_name,
+        proposed_transaction: signed_proposal,
+        target_organizations: proposed_transaction.endorsing_organizations
+      )
+    end
+
+    #
+    # Creates a new endorse request from this proposal.
+    #
+    # @return [Gateway::EndorseRequest] EndorseRequest protobuf message
+    #
+    def new_endorse_request
+      ::Gateway::EndorseRequest.new(
+        transaction_id: transaction_id,
+        channel_id: network_name,
+        proposed_transaction: signed_proposal,
+        endorsing_organizations: proposed_transaction.endorsing_organizations
+      )
+    end
+
+    #
+    # Creates a new prepared transaction from a transaction envelope.
+    #
+    # @param [Common::Envelope] envelope transaction envelope
+    #
+    # @return [Gateway::PreparedTransaction] prepared transaction protobuf message
+    #
+    def new_prepared_transaction(envelope)
+      ::Gateway::PreparedTransaction.new(
+        transaction_id: transaction_id,
+        envelope: envelope
+      )
+    end
+  end
+end

data/lib/fabric/entities/proposed_transaction.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Fabric
+  #
+  # Manages the instantiation and creation of the Gateway::ProposedTransaction Protobuf Message.
+  #
+  # Adapted from official fabric-gateway SDK ProposalBuilder and hyperledger-fabric-sdk:
+  # https://github.com/hyperledger/fabric-gateway/blob/1518e03ed3d6db1b6809e23e61a92744fd18e724/node/src/proposalbuilder.ts
+  # https://github.com/kirshin/hyperledger-fabric-sdk/blob/95a5a1a37001852312df25946e960a9ff149207e/lib/fabric/proposal.rb
+  class ProposedTransaction
+    attr_reader :contract,
+                :transaction_name,
+                :transient_data,
+                :arguments,
+                :proposed_transaction
+
+    # Specifies the set of organizations that will attempt to endorse the proposal.
+    # No other organizations' peers will be sent this proposal.
+    # This is usually used in conjunction with transientData for private data scenarios.
+    attr_reader :endorsing_organizations
+
+    # @!parse include Fabric::Accessors::Network
+    # @!parse include Fabric::Accessors::Gateway
+    include Fabric::Accessors::Contract
+
+    def initialize(contract, transaction_name, arguments: [], transient_data: {}, endorsing_organizations: [])
+      @contract = contract
+      @transaction_name = transaction_name
+      @arguments = arguments
+      @transient_data = transient_data
+      @endorsing_organizations = endorsing_organizations
+
+      generate_proposed_transaction
+    end
+
+    #
+    # Builds the proposed transaction protobuf message
+    #
+    # @return [Gateway::ProposedTransaction]
+    #
+    def generate_proposed_transaction
+      @proposed_transaction = ::Gateway::ProposedTransaction.new(
+        transaction_id: transaction_id,
+        proposal: signed_proposal,
+        endorsing_organizations: endorsing_organizations
+      )
+    end
+
+    def signed_proposal
+      @signed_proposal ||= Protos::SignedProposal.new(
+        proposal_bytes: proposal.to_proto
+      )
+    end
+
+    def proposal
+      @proposal ||= Protos::Proposal.new header: header.to_proto,
+                                         payload: chaincode_proposal_payload.to_proto
+    end
+
+    def header
+      Common::Header.new channel_header: channel_header.to_proto,
+                         signature_header: signature_header.to_proto
+    end
+
+    def channel_header
+      Common::ChannelHeader.new type: Common::HeaderType::ENDORSER_TRANSACTION,
+                                channel_id: network_name, tx_id: transaction_id,
+                                extension: channel_header_extension.to_proto,
+                                timestamp: timestamp, epoch: 0
+      # version: Constants::CHANNEL_HEADER_VERSION # official SDK does not send this.
+    end
+
+    def channel_header_extension
+      Protos::ChaincodeHeaderExtension.new chaincode_id: chaincode_id
+    end
+
+    def chaincode_id
+      Protos::ChaincodeID.new name: chaincode_name
+    end
+
+    def chaincode_proposal_payload
+      chaincode_input = Protos::ChaincodeInput.new args: [transaction_name] + arguments
+      chaincode_spec = Protos::ChaincodeSpec.new type: Protos::ChaincodeSpec::Type::NODE,
+                                                 chaincode_id: chaincode_id,
+                                                 input: chaincode_input
+      input = Protos::ChaincodeInvocationSpec.new chaincode_spec: chaincode_spec
+
+      Protos::ChaincodeProposalPayload.new input: input.to_proto, TransientMap: transient_data
+    end
+
+    #
+    # Returns the current timestamp
+    #
+    # @return [Google::Protobuf::Timestamp] gRPC timestamp
+    #
+    def timestamp
+      now = Time.now
+
+      @timestamp ||= Google::Protobuf::Timestamp.new seconds: now.to_i, nanos: now.nsec
+    end
+
+    #
+    # Generates a random nonce
+    #
+    # @return [String] random nonce
+    #
+    def nonce
+      @nonce ||= signer.crypto_suite.generate_nonce
+    end
+
+    #
+    # Generates a unique transaction ID for the transaction based on a random number and the signer
+    # or returns the existing transaction ID if it has already been generated.
+    #
+    # @return [String] transaction ID
+    #
+    def transaction_id
+      @transaction_id ||= signer.crypto_suite.hexdigest(nonce + signer.to_proto)
+    end
+
+    #
+    # Generates a SignatureHeader protobuf message from the signer and nonce
+    #
+    # @return [Common::SignatureHeader] signature header protobuf message instance
+    #
+    def signature_header
+      Common::SignatureHeader.new creator: signer.to_proto, nonce: nonce
+    end
+
+    # Dev note: if we have more classes that encapsulate protobuffer messages, consider
+    # creating an EncapsulatedPBMessage to hold the message and expose the following methods
+    # as common interface.
+
+    #
+    # Returns the protobuf message instance
+    #
+    # @return [Gateway::ProposedTransaction] protobuf message instance
+    #
+    def as_proto
+      proposed_transaction
+    end
+
+    #
+    # Returns the serialized Protobuf binary form of the proposed transaction
+    #
+    # @return [String] serialized Protobuf binary form of the proposed transaction
+    #
+    def to_proto
+      proposed_transaction.to_proto
+    end
+
+    #
+    # Returns the serialized JSON form of the proposed transaction
+    #
+    # @param [Hash] options JSON serialization options @see https://ruby-doc.org/stdlib-2.6.3/libdoc/json/rdoc/JSON.html#method-i-generate
+    #
+    # @return [String] serialized JSON form of the proposed transaction
+    #
+    def to_json(options = {})
+      proposed_transaction.to_json(options)
+    end
+  end
+end

data/lib/fabric/entities/status.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Fabric
+  #
+  # Status of a transaction that is to be committed to the ledger.
+  #
+  class Status
+    TRANSACTION_STATUSES = ::Protos::TxValidationCode.constants.map(&::Protos::TxValidationCode.method(:const_get))
+                                                     .collect do |i|
+      [::Protos::TxValidationCode.lookup(i), i]
+    end.to_h
+
+    # @return [Integer] Block number in which the transaction committed.
+    attr_reader :block_number
+
+    # @return [Integer] Transaction status
+    attr_reader :code
+
+    # @return [Boolean] `true` if the transaction committed successfully; otherwise `false`.
+    attr_reader :successful
+
+    # @return [String] The ID of the transaction.
+    attr_reader :transaction_id
+
+    def initialize(transaction_id, block_number, code)
+      @transaction_id = transaction_id
+      @block_number = block_number
+      @code = code
+      @successful = @code == TRANSACTION_STATUSES[:VALID]
+    end
+  end
+end

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/gateway.rb

@@ -1,10 +1,35 @@
-require "fabric/gateway/version"
-require "gateway/gateway_pb"
-require "gateway/gateway_services_pb"
+# frozen_string_literal: true
 
 module Fabric
-  module Gateway
-    class Error < StandardError; end
-    # Your code goes here...
+  #
+  # Gateway represents the connection of a specific client identity to a Fabric Gateway.
+  #
+  class Gateway
+    attr_reader :signer, :client
+
+    #
+    # Initialize a new Gateway
+    #
+    # @param [Fabric::Identity] signer identity utilized to sign transactions
+    # @param [Fabric::Client] client Gateway Client
+    #
+    def initialize(signer, client)
+      raise InvalidArgument, 'signer must be Fabric::Identity' unless signer.is_a? Fabric::Identity
+      raise InvalidArgument, 'client must be Fabric::Client' unless client.is_a? Fabric::Client
+
+      @signer = signer
+      @client = client
+    end
+
+    #
+    # Initialize new network from the Gateway
+    #
+    # @param [string] name channel name
+    #
+    # @return [Fabric::Network] returns a new network
+    #
+    def new_network(name)
+      Network.new(self, name)
+    end
   end
 end