flow-ruby 0.2.1

data/lib/flow/access/access_services_pb.rb

@@ -0,0 +1,87 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# Source: flow/access/access.proto for package 'flow.access'
+
+require 'grpc'
+require 'flow/access/access_pb'
+
+module Flow
+  module Access
+    module AccessAPI
+      # AccessAPI is the public-facing API provided by access nodes.
+      class Service
+
+        include GRPC::GenericService
+
+        self.marshal_class_method = :encode
+        self.unmarshal_class_method = :decode
+        self.service_name = 'flow.access.AccessAPI'
+
+        # Ping is used to check if the access node is alive and healthy.
+        rpc :Ping, ::Flow::Access::PingRequest, ::Flow::Access::PingResponse
+        # Block Headers
+        #
+        # GetLatestBlockHeader gets the latest sealed or unsealed block header.
+        rpc :GetLatestBlockHeader, ::Flow::Access::GetLatestBlockHeaderRequest, ::Flow::Access::BlockHeaderResponse
+        # GetBlockHeaderByID gets a block header by ID.
+        rpc :GetBlockHeaderByID, ::Flow::Access::GetBlockHeaderByIDRequest, ::Flow::Access::BlockHeaderResponse
+        # GetBlockHeaderByHeight gets a block header by height.
+        rpc :GetBlockHeaderByHeight, ::Flow::Access::GetBlockHeaderByHeightRequest, ::Flow::Access::BlockHeaderResponse
+        # Blocks
+        #
+        # GetLatestBlock gets the full payload of the latest sealed or unsealed block.
+        rpc :GetLatestBlock, ::Flow::Access::GetLatestBlockRequest, ::Flow::Access::BlockResponse
+        # GetBlockByID gets a full block by ID.
+        rpc :GetBlockByID, ::Flow::Access::GetBlockByIDRequest, ::Flow::Access::BlockResponse
+        # GetBlockByHeight gets a full block by height.
+        rpc :GetBlockByHeight, ::Flow::Access::GetBlockByHeightRequest, ::Flow::Access::BlockResponse
+        # Collections
+        #
+        # GetCollectionByID gets a collection by ID.
+        rpc :GetCollectionByID, ::Flow::Access::GetCollectionByIDRequest, ::Flow::Access::CollectionResponse
+        # Transactions
+        #
+        # SendTransaction submits a transaction to the network.
+        rpc :SendTransaction, ::Flow::Access::SendTransactionRequest, ::Flow::Access::SendTransactionResponse
+        # GetTransaction gets a transaction by ID.
+        rpc :GetTransaction, ::Flow::Access::GetTransactionRequest, ::Flow::Access::TransactionResponse
+        # GetTransactionResult gets the result of a transaction.
+        rpc :GetTransactionResult, ::Flow::Access::GetTransactionRequest, ::Flow::Access::TransactionResultResponse
+        # Accounts
+        #
+        # GetAccount is an alias for GetAccountAtLatestBlock.
+        #
+        # Warning: this function is deprecated. It behaves identically to GetAccountAtLatestBlock and will be removed in a future version.
+        rpc :GetAccount, ::Flow::Access::GetAccountRequest, ::Flow::Access::GetAccountResponse
+        # GetAccountAtLatestBlock gets an account by address from the latest sealed execution state.
+        rpc :GetAccountAtLatestBlock, ::Flow::Access::GetAccountAtLatestBlockRequest, ::Flow::Access::AccountResponse
+        # GetAccountAtBlockHeight gets an account by address at the given block height
+        rpc :GetAccountAtBlockHeight, ::Flow::Access::GetAccountAtBlockHeightRequest, ::Flow::Access::AccountResponse
+        # Scripts
+        #
+        # ExecuteScriptAtLatestBlock executes a read-only Cadence script against the latest sealed execution state.
+        rpc :ExecuteScriptAtLatestBlock, ::Flow::Access::ExecuteScriptAtLatestBlockRequest, ::Flow::Access::ExecuteScriptResponse
+        # ExecuteScriptAtBlockID executes a ready-only Cadence script against the execution state at the block with the given ID.
+        rpc :ExecuteScriptAtBlockID, ::Flow::Access::ExecuteScriptAtBlockIDRequest, ::Flow::Access::ExecuteScriptResponse
+        # ExecuteScriptAtBlockHeight executes a ready-only Cadence script against the execution state at the given block height.
+        rpc :ExecuteScriptAtBlockHeight, ::Flow::Access::ExecuteScriptAtBlockHeightRequest, ::Flow::Access::ExecuteScriptResponse
+        # Events
+        #
+        # GetEventsForHeightRange retrieves events emitted within the specified block range.
+        rpc :GetEventsForHeightRange, ::Flow::Access::GetEventsForHeightRangeRequest, ::Flow::Access::EventsResponse
+        # GetEventsForBlockIDs retrieves events for the specified block IDs and event type.
+        rpc :GetEventsForBlockIDs, ::Flow::Access::GetEventsForBlockIDsRequest, ::Flow::Access::EventsResponse
+        # NetworkParameters
+        #
+        # GetNetworkParameters retrieves the Flow network details
+        rpc :GetNetworkParameters, ::Flow::Access::GetNetworkParametersRequest, ::Flow::Access::GetNetworkParametersResponse
+        # ProtocolState
+        #
+        # GetLatestProtocolStateSnapshot retrieves the latest sealed protocol state snapshot.
+        # Used by Flow nodes joining the network to bootstrap a space-efficient local state.
+        rpc :GetLatestProtocolStateSnapshot, ::Flow::Access::GetLatestProtocolStateSnapshotRequest, ::Flow::Access::ProtocolStateSnapshotResponse
+      end
+
+      Stub = Service.rpc_stub_class
+    end
+  end
+end

data/lib/flow/client.rb

@@ -0,0 +1,358 @@
+# frozen_string_literal: true
+
+module Flow
+  #
+  # The client class is used to access the Flow API
+  #
+  class Client
+    NODES = {
+      mainnet: "access.mainnet.nodes.onflow.org:9000",
+      testnet: "access.devnet.nodes.onflow.org:9000",
+      canarynet: "access.canary.nodes.onflow.org:9000"
+    }.freeze
+
+    #
+    # @param node [Symbol, String] the node address used in the stub
+    #
+    def initialize(node: :mainnet)
+      @stub = Access::AccessAPI::Stub.new(detect_node(node), :this_channel_is_insecure)
+    end
+
+    #
+    # Check if the Access API is ready and available
+    #
+    # @return [Flow::Access::PingResponse]
+    #
+    def ping
+      @stub.ping(Access::PingRequest.new)
+    end
+
+    ####
+    # Block Headers
+    #
+    # The following methods query information about block headers
+    ####
+
+    #
+    # Get the latest sealed or unsealed block header
+    #
+    # @param is_sealed [Boolean]
+    #
+    # @return [Flow::Entities::BlockHeader]
+    #
+    def get_latest_block_header(is_sealed: false)
+      req = Access::GetLatestBlockHeaderRequest.new(is_sealed: is_sealed)
+      res = @stub.get_latest_block_header(req)
+      res.block
+    end
+
+    #
+    # Get a block header by ID
+    #
+    # @todo The ID should be +bytes+ or it should be formatted automatically
+    #
+    # @param id [String]
+    #
+    # @return [Flow::Entities::BlockHeader]
+    #
+    def get_block_header_by_id(id)
+      req = Access::GetBlockHeaderByIDRequest.new(id: id)
+      res = @stub.get_block_header_by_id(req)
+      res.block
+    end
+
+    #
+    # Get a block header by height
+    #
+    # @param height [uint64]
+    #
+    # @return [Flow::Entities::BlockHeader]
+    #
+    def get_block_header_by_height(height)
+      req = Access::GetBlockHeaderByHeightRequest.new(height: height)
+      res = @stub.get_block_header_by_height(req)
+      res.block
+    end
+
+    ####
+    # Blocks
+    #
+    # The following methods query information about full blocks
+    ####
+
+    #
+    # Get the full payload of the latest sealed or unsealed block
+    #
+    # @param is_sealed [Boolean]
+    #
+    # @return [Flow::Entities::Block]
+    #
+    def get_latest_block(is_sealed: false)
+      req = Access::GetLatestBlockRequest.new(is_sealed: is_sealed)
+      res = @stub.get_latest_block(req)
+      res.block
+    end
+
+    #
+    # Get a full block by ID
+    #
+    # @todo The ID should be +bytes+ or it should be formatted automatically
+    #
+    # @param id [String]
+    #
+    # @return [Flow::Entities::Block]
+    #
+    def get_block_by_id(id)
+      req = Access::GetBlockByIDRequest.new(id: id)
+      res = @stub.get_block_by_id(req)
+      res.block
+    end
+
+    #
+    # Get a full block by height
+    #
+    # @param height [uint64]
+    #
+    # @return [Flow::Entities::Block]
+    #
+    def get_block_by_height(height)
+      req = Access::GetBlockByHeightRequest.new(height: height)
+      res = @stub.get_block_by_height(req)
+      res.block
+    end
+
+    ####
+    # Collections
+    #
+    # The following methods query information about collections
+    ####
+
+    #
+    # Gets a collection by ID
+    #
+    # @todo The ID should be +bytes+ or it should be formatted automatically
+    #
+    # @param id [String]
+    #
+    # @return [Flow::Entities::Collection]
+    #
+    def get_collection_by_id(id)
+      req = Access::GetCollectionByIDRequest.new(id: id)
+      res = @stub.get_collection_by_id(req)
+      res.collection
+    end
+
+    ####
+    # Transactions
+    #
+    # The following methods can be used to submit transactions and fetch their results
+    ####
+
+    #
+    # Submit a transaction to the network
+    #
+    #
+    #
+    #
+    # def send_transaction()
+    #   # TODO: build and sign transaction here
+    #   # req = Access::SendTransactionRequest.new()
+    #   # @stub.send_transaction(req)
+    # end
+
+    #
+    # Get a transaction by ID
+    #
+    # @todo The ID should be +bytes+ or it should be formatted automatically
+    #
+    # @param id [String]
+    #
+    # @return [Flow::Entities::Transaction]
+    #
+    def get_transaction(id)
+      req = Access::GetTransactionRequest.new(id: id)
+      res = @stub.get_transaction(req)
+      res.transaction
+    end
+
+    #
+    # Get the execution result of a transaction
+    #
+    # @todo The ID should be +bytes+ or it should be formatted automatically
+    # @todo We might want to change the return value here, TransactionReturnResponse has
+    #   these available keys: status, status_code, error_message, events
+    #
+    # @param id [String]
+    #
+    # @return [Flow::Access::TransactionResultResponse]
+    #
+    def get_transaction_result(id)
+      req = Access::GetTransactionRequest.new(id: id)
+      @stub.get_transaction_result(req)
+    end
+
+    ####
+    # Accounts
+    ####
+
+    #
+    # Get an account by address
+    #
+    # @param address [String]
+    #
+    # @return [Flow::Entities::Account]
+    #
+    def get_account_at_latest_block(address)
+      req = Access::GetAccountAtLatestBlockRequest.new(address: to_bytes(address))
+      res = @stub.get_account_at_latest_block(req)
+      res.account
+    end
+
+    #
+    # Get an account by address at the given block height
+    #
+    # @param address [String]
+    # @param block_height [uint64]
+    #
+    # @return [Flow::Entities::Account]
+    #
+    def get_account_at_block_height(address, block_height)
+      req = Access::GetAccountAtBlockHeightRequest.new(
+        address: to_bytes(address),
+        block_height: block_height
+      )
+
+      res = @stub.get_account_at_latest_block(req)
+      res.account
+    end
+
+    ####
+    # Scripts
+    ####
+
+    #
+    # Execute a read-only Cadence script against the latest sealed execution state
+    #
+    # @param script [String] cadence script
+    # @param args [Array] array of args
+    #
+    # @return [OpenStruct]
+    #
+    def execute_script(script, args = [])
+      req = Access::ExecuteScriptAtLatestBlockRequest.new(
+        script: script,
+        arguments: args
+      )
+
+      res = @stub.execute_script_at_latest_block(req)
+      parse_json(res.value)
+    end
+
+    ####
+    # Events
+    #
+    # The following methods can be used to query for on-chain events
+    ####
+
+    #
+    # Retrieve events emitted within the specified block range
+    #
+    # @todo Scope the response further
+    #
+    # @param type [String]
+    # @param start_height [uint64]
+    # @param end_height [uint64]
+    #
+    # @return [EventsResponse]
+    #
+    def get_events_for_height_range(type, start_height: 2, end_height: 3)
+      req = Access::GetEventsForHeightRangeRequest.new(
+        type: type,
+        start_height: start_height,
+        end_height: end_height
+      )
+
+      @stub.get_events_for_height_range(req)
+    end
+
+    #
+    # Retrieve events for the specified block IDs and event type
+    #
+    # @todo Scope the response further
+    #
+    # @param type [String]
+    # @param block_ids [Array]
+    #
+    # @return [EventsResponse]
+    #
+    def get_events_for_block_ids(type, block_ids = [])
+      req = Access::GetEventsForBlockIDsRequest.new(
+        type: type,
+        block_ids: block_ids
+      )
+
+      @stub.get_events_for_block_ids(req)
+    end
+
+    ####
+    # Network Parameters
+    #
+    # Network parameters provide information about the Flow network.
+    #   Currently, it only includes the chain ID.
+    #   The following method can be used to query for network parameters
+    ####
+
+    #
+    # Retrieve the network parameters
+    #
+    # @return [Hash]
+    #
+    def get_network_parameters
+      req = Access::GetNetworkParametersRequest.new
+      res = @stub.get_network_parameters(req)
+      res.to_h
+    end
+
+    ####
+    # Protocol state snapshot
+    #
+    # The following method can be used to query the latest protocol state snapshot
+    ####
+
+    #
+    # Retrieve the latest Protocol state snapshot serialized as a byte array.
+    #   It is used by Flow nodes joining the network to bootstrap a space-efficient local state
+    #
+    # @todo Fix. This currently fails with unimplemented_error
+    #
+    # @return
+    #
+    def get_latest_protocol_state_snapshot
+      req = Access::GetLatestProtocolStateSnapshotRequest.new
+      @stub.get_latest_protocol_state_snapshot(req)
+    end
+
+    private
+
+    def detect_node(node)
+      case node.to_sym
+      when :mainnet   then NODES[:mainnet]
+      when :testnet   then NODES[:testnet]
+      when :canarynet then NODES[:canarynet]
+      else                 node
+      end
+    end
+
+    def parse_json(event_payload)
+      JSON.parse(event_payload, object_class: OpenStruct)
+    end
+
+    def to_bytes(string)
+      [string].pack("H*")
+    end
+
+    def to_string(bytes)
+      bytes.unpack1("H*")
+    end
+  end
+end

data/lib/flow/entities/account_pb.rb

@@ -0,0 +1,32 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: flow/entities/account.proto
+
+require 'google/protobuf'
+
+Google::Protobuf::DescriptorPool.generated_pool.build do
+  add_file("flow/entities/account.proto", :syntax => :proto3) do
+    add_message "flow.entities.Account" do
+      optional :address, :bytes, 1
+      optional :balance, :uint64, 2
+      optional :code, :bytes, 3
+      repeated :keys, :message, 4, "flow.entities.AccountKey"
+      map :contracts, :string, :bytes, 5
+    end
+    add_message "flow.entities.AccountKey" do
+      optional :index, :uint32, 1
+      optional :public_key, :bytes, 2
+      optional :sign_algo, :uint32, 3
+      optional :hash_algo, :uint32, 4
+      optional :weight, :uint32, 5
+      optional :sequence_number, :uint32, 6
+      optional :revoked, :bool, 7
+    end
+  end
+end
+
+module Flow
+  module Entities
+    Account = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("flow.entities.Account").msgclass
+    AccountKey = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("flow.entities.AccountKey").msgclass
+  end
+end