fabric-gateway 0.0.1 → 0.3.0

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

data/lib/fabric/network.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Fabric
+  #
+  # Network represents a blockchain network, or Fabric channel. The Network can be used to access deployed smart
+  # contracts, and to listen for events emitted when blocks are committed to the ledger.
+  #
+  # JChan & THowe believe this should be called a Channel, however Hyperledger Fabric has decided upon the terminology
+  # network - https://github.com/hyperledger/fabric-gateway/issues/355#issuecomment-997888071
+  #
+  class Network
+    attr_reader :gateway, :name
+
+    # @!parse include Fabric::Accessors::Gateway
+    include Fabric::Accessors::Gateway
+
+    def initialize(gateway, name)
+      @gateway = gateway
+      @name = name
+    end
+
+    #
+    # Creates a new contract instance
+    #
+    # @param [string] chaincode_name name of the chaincode
+    # @param [string] contract_name optional name of the contract
+    #
+    # @return [Fabric::Contract] new contract instance
+    #
+    def new_contract(chaincode_name, contract_name = '')
+      Contract.new(self, chaincode_name, contract_name)
+    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
+    #
+    # @return [?] ?
+    #
+    def new_chaincode_events
+      raise NotYetImplemented
+    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
+    #
+    # @return [?] ?
+    #
+    def new_chaincode_events_request
+      raise NotImplementedError
+    end
+  end
+end

data/lib/fabric/version.rb

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

data/lib/fabric.rb

@@ -0,0 +1,57 @@
+# 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/constants'
+require 'fabric/contract'
+require 'fabric/client'
+require 'fabric/ec_crypto_suite'
+require 'fabric/gateway'
+require 'fabric/network'
+require 'fabric/version'
+
+#
+# Hyperledger Fabric Gateway SDK
+#
+module Fabric
+  class Error < StandardError; end
+  class InvalidArgument < Error; end
+  class NotYetImplemented < Error; end
+
+  #
+  # 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} - " +
+        Status::TRANSACTION_STATUSES.key(status.code).to_s)
+      @code = code
+      @transaction_id = status.transaction_id
+    end
+  end
+
+  def self.crypto_suite(opts = {})
+    @crypto_suite ||= Fabric::ECCryptoSuite.new opts
+  end
+end