near 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf5d4ecbf47a20dcb7316560abfdf3317505824ed2a501dc769e53186db46571
-  data.tar.gz: 5745b4bd4742054e9c5e710b4e267795636fd4d82c0866a3209ed804c306b25a
+  metadata.gz: 1d113e40c4ca1414cd8bff319acdaeba7d7cd1a07ebc866ce875afd2080e44b1
+  data.tar.gz: ae7151a4a1022ecf3b9d652ae11bcabfffc427ccaad0cc07858fd662fb91cbd8
 SHA512:
-  metadata.gz: b877435cf142fab1a9d2f4b6651f1993dbf05b7c8eeea28cc76ea9ac6930a855a6570576ae5fb8012e869949efd1b56ca6cce5474bd318735996c9b8713d74f9
-  data.tar.gz: a0e57d4a298b6e52d320a9c2be9ccc8aef0f6abe7ed24e18535c6dbc0fffdbe153f3b8fa3c676cc33ac5823824d1a878175778684c88d1e272354d841ba9a388
+  metadata.gz: 779325138cf044d38991e1911d8bf115f8559d86a530bda11e0b97a75367406386b63e81a7e9a3d9db69b70ab826ce146e0b326efdb9e69dcf3545083227c1bb
+  data.tar.gz: f5b55100bc19a9c8d3e6c165e66d7780b94a60ed1fea90bce0523cf77657b384b13c1439c8aabbc4db2b6d2ae5534ef186ad9d7ed82dd2bb3e85ee915f5e1fb0

data/CHANGES.md

@@ -5,21 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.3.1 - 2025-02-05
+
+## 0.3.0 - 2025-02-02
+
+### Added
+- Implement block data accessors
+- Implement transaction data accessors
+- Implement action parsing
+
+### Changed
+- Adopt Faraday as the HTTP client
+- Improve HTTP error handling and retries
+
 ## 0.2.0 - 2025-01-29
 
 ### Added
-- `Network#fetch(block)`.
-- `NEAR.testnet`, `NEAR.mainnet`.
+- `Network#fetch(block)`
+- `NEAR.testnet`, `NEAR.mainnet`
 
 ### Changed
-- Use the NEAR_CLI environmnet variable, if set.
-- Use a temporary file for `call_function`.
-- Enhance `call_function()`.
-- Enhance `create_account_with_funding()`.
-- Enhance `delete_account()`.
+- Use the NEAR_CLI environmnet variable, if set
+- Use a temporary file for `call_function`
+- Enhance `call_function()`
+- Enhance `create_account_with_funding()`
+- Enhance `delete_account()`
 
 ### Fixed
-- Fix the formatting of balances.
+- Fix the formatting of balances
 
 ## 0.1.0 - 2025-01-19
 

data/README.md

@@ -6,10 +6,13 @@
 [![Documentation](https://img.shields.io/badge/rubydoc-latest-blue)](https://rubydoc.info/gems/near)
 
 **NEAR.rb** is a [Ruby] client library for the [NEAR Protocol].
-It wraps the [NEAR command-line interface] (CLI) into a Ruby interface.
+It provides a [neardata.xyz] API client for block data as well as wraps the
+[NEAR Command-Line Interface] (CLI) in a high-productivity Ruby interface.
 
 ## ✨ Features
 
+- Fetches block data from the [neardata.xyz] API.
+- Supports parsing of block, chunk, transaction, and action data.
 - Wraps the complete CLI features in an idiomatic Ruby interface.
 - Provides comprehensive account management operations.
 - Supports token operations for NEAR and other assets.
@@ -17,14 +20,13 @@ It wraps the [NEAR command-line interface] (CLI) into a Ruby interface.
 - Handles transaction construction, signing, and monitoring.
 - Integrates with hardware wallets and secure key storage.
 - Implements type-safe balance operations and input validation.
-- Fetches block data from the [neardata.xyz] API.
 - Supports both the [mainnet] and [testnet] environments.
 - Offers cross-platform support with zero library dependencies.
 - 100% free and unencumbered public domain software.
 
 ## 🛠️ Prerequisites
 
-- [NEAR CLI] 0.19+
+- [NEAR CLI] 0.18+
 - [Ruby] 3.0+
 
 ## ⬇️ Installation
@@ -37,6 +39,23 @@ gem install near
 
 ## 👉 Examples
 
+- [Importing the library](#importing-the-library)
+- [Fetching block information](#fetching-block-information)
+- [Tracking block production](#tracking-block-production)
+- [Tracking chain transactions](#tracking-chain-transactions)
+- [Tracking chain actions](#tracking-chain-actions)
+- [Tracking contract interactions](#tracking-contract-interactions)
+- [Instantiating the CLI wrapper](#instantiating-the-cli-wrapper)
+- [Viewing account details](#viewing-account-details)
+- [Importing accounts](#importing-accounts)
+- [Creating accounts](#creating-accounts)
+- [Deleting accounts](#deleting-accounts)
+- [Managing access keys](#managing-access-keys)
+- [Managing tokens](#managing-tokens)
+- [Calling read-only contract methods](#calling-read-only-contract-methods)
+- [Calling mutative contract methods](#calling-mutative-contract-methods)
+- [Deploying a smart contract](#deploying-a-smart-contract)
+
 ### Importing the library
 
 ```ruby
@@ -53,6 +72,68 @@ global edge locations:
 block = NEAR.testnet.fetch(186_132_854)
 ```
 
+### Tracking block production
+
+Thanks to the built-in [neardata.xyz] API client, it is trivial to
+track the current tip of the chain in a robust and efficient manner:
+
+```ruby
+NEAR.testnet.fetch_blocks do |block|
+  puts [block.height, block.hash].join("\t")
+end
+```
+
+### Tracking chain transactions
+
+```ruby
+NEAR.testnet.fetch_blocks do |block|
+  puts block.inspect
+
+  block.each_transaction do |transaction|
+    puts "\t" + transaction.inspect
+  end
+end
+```
+
+For a more elaborated example, see
+[`examples/monitor_all_transactions.rb`](examples/monitor_all_transactions.rb):
+
+[![monitor_all_transactions.rb](examples/monitor_all_transactions.gif)](examples/monitor_all_transactions.gif)
+
+### Tracking chain actions
+
+```ruby
+NEAR.testnet.fetch_blocks do |block|
+  puts block.inspect
+
+  block.each_action do |action|
+    puts "\t" + action.inspect
+  end
+end
+```
+
+For a more elaborated example, see
+[`examples/monitor_all_actions.rb`](examples/monitor_all_actions.rb):
+
+[![monitor_all_actions.rb](examples/monitor_all_actions.gif)](examples/monitor_all_actions.gif)
+
+### Tracking contract interactions
+
+```ruby
+NEAR.testnet.fetch_blocks do |block|
+  puts block.inspect
+
+  block.find_actions(:FunctionCall, receiver: 'aurora', method_name: /^submit/) do |action|
+    puts "\t" + action.inspect
+  end
+end
+```
+
+For a more elaborated example, see
+[`examples/index_evm_transactions.rb`](examples/index_evm_transactions.rb):
+
+[![index_evm_transactions.rb](examples/index_evm_transactions.gif)](examples/index_evm_transactions.gif)
+
 ### Instantiating the CLI wrapper
 
 ```ruby
@@ -106,7 +187,7 @@ result = testnet.import_account_with_private_key(
 # Create an account funded from a faucet (testnet only):
 result = testnet.create_account_with_faucet(
   'mynewaccount.testnet',
-  'ed25519:HVPgAsZkZ7cwLZDqK313XJsDyqAvgBxrATcD7VacA8KE'
+  public_key: 'ed25519:HVPgAsZkZ7cwLZDqK313XJsDyqAvgBxrATcD7VacA8KE'
 )
 
 # Create an account funded by another account:
@@ -126,8 +207,8 @@ result = testnet.create_implicit_account('/path/to/credentials/folder')
 ```ruby
 # Delete an existing account:
 result = testnet.delete_account(
-  'todelete.testnet',     # account to delete
-  'beneficiary.testnet'   # account receiving remaining balance
+  'my-obsolete-account.testnet',                # account to delete
+  beneficiary: 'v2.faucet.nonofficial.testnet'  # account receiving remaining balance
 )
 ```
 

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.1

data/lib/near/account.rb

@@ -5,10 +5,20 @@
 #
 # @see https://nomicon.io/DataStructures/Account
 class NEAR::Account
+  ##
+  # @param [String, #to_s] id
+  # @return [NEAR::Account]
   def self.parse(id)
     self.new(id.to_s)
   end
 
+  ##
+  # @return [NEAR::Account]
+  def self.temp
+    timestamp = (Time.now.to_f * 1_000).to_i
+    self.new("temp-#{timestamp}.testnet")
+  end
+
   ##
   # @param [String, #to_s] id
   def initialize(id)

data/lib/near/action.rb

@@ -0,0 +1,141 @@
+# This is free and unencumbered software released into the public domain.
+
+require 'base64'
+require 'json'
+
+##
+# Represents a NEAR action.
+#
+# @see https://nomicon.io/RuntimeSpec/Actions
+class NEAR::Action
+  class CreateAccount < NEAR::Action; end
+
+  class DeployContract < NEAR::Action; end
+
+  class FunctionCall < NEAR::Action
+    ##
+    # @return [String]
+    attr_reader :method_name
+    def method_name
+      @data['method_name']
+    end
+
+    ##
+    # @return [String]
+    def json_args
+      @json_args ||= JSON.parse(self.args)
+    end
+
+    ##
+    # @param [Symbol, String, #to_s] key
+    # @return [Object]
+    def [](key)
+      self.json_args[key.to_s] rescue nil
+    end
+
+    ##
+    # @return [String]
+    attr_reader :args
+    def args
+      @args ||= Base64.decode64(@data['args'])
+    end
+
+    ##
+    # @return [Integer]
+    attr_reader :gas
+    def gas
+      @data['gas']
+    end
+
+    ##
+    # @return [NEAR::Balance]
+    attr_reader :deposit
+    def deposit
+      @deposit ||= NEAR::Balance.parse(@data['deposit'])
+    end
+  end
+
+  class Transfer < NEAR::Action
+    ##
+    # @return [NEAR::Balance]
+    attr_reader :deposit
+    def deposit
+      @deposit ||= NEAR::Balance.parse(@data['deposit'])
+    end
+  end
+
+  class Stake < NEAR::Action; end
+
+  class AddKey < NEAR::Action; end
+
+  class DeleteKey < NEAR::Action; end
+
+  class DeleteAccount < NEAR::Action; end
+
+  class Delegate < NEAR::Action; end
+
+  ##
+  # @param [String, Hash] data
+  # @return [NEAR::Action]
+  def self.parse(data)
+    case
+      when data.is_a?(String) then case
+        when 'CreateAccount' then CreateAccount.new
+        when 'DeployContract' then DeployContract.new
+        when 'FunctionCall' then FunctionCall.new
+        when 'Transfer' then Transfer.new
+        when 'Stake' then Stake.new
+        when 'AddKey' then AddKey.new
+        when 'DeleteKey' then DeleteKey.new
+        when 'DeleteAccount' then DeleteAccount.new
+        when 'Delegate' then Delegate.new
+        else self.new
+      end
+      when data['CreateAccount'] then CreateAccount.new(data['CreateAccount'])
+      when data['DeployContract'] then DeployContract.new(data['DeployContract'])
+      when data['FunctionCall'] then FunctionCall.new(data['FunctionCall'])
+      when data['Transfer'] then Transfer.new(data['Transfer'])
+      when data['Stake'] then Stake.new(data['Stake'])
+      when data['AddKey'] then AddKey.new(data['AddKey'])
+      when data['DeleteKey'] then DeleteKey.new(data['DeleteKey'])
+      when data['DeleteAccount'] then DeleteAccount.new(data['DeleteAccount'])
+      when data['Delegate'] then Delegate.new(data['Delegate'])
+      else self.new(data[data.keys.first])
+    end
+  end
+
+  ##
+  # @param [Hash, #to_h] data
+  def initialize(data = nil)
+    @data = data.to_h if data
+  end
+
+  ##
+  # @return [Symbol]
+  attr_reader :type
+  def type
+    self.class.name.split('::').last.to_sym
+  end
+
+  ##
+  # The action data.
+  #
+  # @return [Hash]
+  attr_reader :data
+
+  ##
+  # @return [Hash]
+  def to_h; @data || {}; end
+
+  ##
+  # @return [Symbol]
+  def to_sym; self.type; end
+
+  ##
+  # @return [String]
+  def inspect
+    data = self.to_h
+    data['args'] = '...' if data['args']
+    "#<#{self.class.name} #{data.to_json}>"
+  end
+end # NEAR::Block

data/lib/near/balance.rb

@@ -5,6 +5,10 @@ require 'bigdecimal'
 ##
 # Represents a NEAR balance.
 class NEAR::Balance
+  def self.parse(s)
+    self.new(s.to_f / 10**24)
+  end
+
   def self.from_near(s)
     self.new(s)
   end
@@ -32,7 +36,7 @@ class NEAR::Balance
   #
   # @return [String]
   def inspect
-    "Ⓝ#{@quantity.to_f}"
+    "Ⓝ #{@quantity.to_f}"
   end
 
   ##

data/lib/near/block.rb

@@ -26,9 +26,11 @@ class NEAR::Block
   ##
   # @param [Integer, #to_i] height
   # @param [String, #to_s] hash
-  def initialize(height: nil, hash: nil)
+  # @param [Hash, #to_h] data
+  def initialize(height: nil, hash: nil, data: nil)
     @height = height.to_i if height
     @hash = hash.to_s if hash
+    @data = data.to_h if data
   end
 
   ##
@@ -43,6 +45,133 @@ class NEAR::Block
   # @return [String]
   attr_reader :hash
 
+  ##
+  # The block data, if fetched.
+  #
+  # @return [Hash]
+  attr_reader :data
+
+  ##
+  # @return [String]
+  attr_reader :author
+  def author
+    self.data['block']['author']
+  end
+
+  ##
+  # The block header.
+  #
+  # @return [Hash]
+  attr_reader :header
+  def header
+    self.data['block']['header']
+  end
+
+  ##
+  # @return [Array<Hash>]
+  attr_reader :chunks
+  def chunks
+    self.data['block']['chunks']
+  end
+
+  ##
+  # @return [Array<Hash>]
+  attr_reader :shards
+  def shards
+    self.data['shards']
+  end
+
+  ##
+  # The set of signers in the transactions in this block.
+  #
+  # @return [Array<NEAR::Account>]
+  def signers
+    self.collect_transaction_field('signer_id')
+      .map { |id| NEAR::Account.new(id) }
+  end
+
+  ##
+  # The set of receivers in the transactions in this block.
+  #
+  # @return [Array<NEAR::Account>]
+  def receivers
+    self.collect_transaction_field('receiver_id')
+      .map { |id| NEAR::Account.new(id) }
+  end
+
+  ##
+  # Enumerates the transactions in this block.
+  #
+  # @yield [NEAR::Transaction]
+  # @yieldparam [NEAR::Transaction] transaction
+  # @yieldreturn [void]
+  # @return [Enumerator] if no block is given
+  def each_transaction(&)
+    return enum_for(:each_transaction) unless block_given?
+    self.each_chunk do |chunk|
+      next if !chunk['transactions']
+      chunk['transactions'].each do |tx|
+        yield NEAR::Transaction.parse(tx)
+      end
+    end
+  end
+
+  ##
+  # Enumerates the actions in this block.
+  #
+  # @yield [NEAR::Action, NEAR::Transaction]
+  # @yieldparam [NEAR::Action] action
+  # @yieldparam [NEAR::Transaction] transaction
+  # @yieldreturn [void]
+  # @return [Enumerator] if no block is given
+  def each_action(&)
+    return enum_for(:each_action) unless block_given?
+    self.each_transaction do |tx|
+      tx.each_action do |action|
+        yield action, tx
+      end
+    end
+  end
+
+  ##
+  # @param [Symbol, #to_sym] type
+  # @param [String, Regexp] signer
+  # @param [String, Regexp] receiver
+  # @param [String, Regexp] method_name
+  # @yield [NEAR::Action, NEAR::Transaction]
+  # @yieldparam [NEAR::Action] action
+  # @yieldparam [NEAR::Transaction] transaction
+  # @yieldreturn [void]
+  # @return [Enumerator] if no block is given
+  def find_actions(type, signer: nil, receiver: nil, method_name: nil, &)
+    return enum_for(:each_action) unless block_given?
+    type = type.to_sym
+    self.each_transaction do |tx|
+      next if signer && !(signer === tx.signer_id)
+      next if receiver && !(receiver === tx.receiver_id)
+      tx.each_action do |action|
+        next unless type == action.type
+        next if method_name && !(method_name === action.method_name)
+        yield action, tx
+      end
+    end
+  end
+
+  ##
+  # Enumerates the chunks in this block.
+  #
+  # @yield [Hash]
+  # @yieldparam [Hash] chunk
+  # @yieldreturn [void]
+  # @return [Enumerator] if no block is given
+  def each_chunk(&)
+    return enum_for(:each_chunk) unless block_given?
+    self.shards.each do |shard|
+      chunk = shard['chunk']
+      yield chunk if chunk
+    end
+  end
+
   ##
   # @return [Array<String>]
   def to_cli_args
@@ -53,13 +182,36 @@ class NEAR::Block
 
   ##
   # @return [Integer]
-  def to_i
-    @height
-  end
+  def to_i; @height; end
 
   ##
   # @return [String]
   def to_s
     (@height || @hash || :now).to_s
   end
+
+  ##
+  # @return [Hash]
+  def to_h; @data; end
+
+  ##
+  # @return [String]
+  def inspect
+    "#<#{self.class.name} height: #{@height}, hash: #{@hash.inspect}>"
+  end
+
+  protected
+
+  ##
+  # @param [String] field
+  # @return [Array<String>]
+  def collect_transaction_field(field)
+    result = {}
+    self.shards.each do |shard|
+      shard['chunk']['transactions'].each do |tx|
+        result[tx['transaction']['receiver_id']] = true
+      end
+    end
+    result.keys
+  end
 end # NEAR::Block

data/lib/near/cli/account.rb

@@ -70,15 +70,20 @@ module NEAR::CLI::Account
   ##
   # Creates a new account sponsored by the faucet service.
   #
-  # @param [String] new_account_id
-  # @param [String] public_key
+  # @param [NEAR::Account, #to_s] new_account
+  # @param [String, nil] public_key
   # @return [String]
-  def create_account_with_faucet(new_account_id, public_key)
+  def create_account_with_faucet(new_account, public_key: nil)
     stdout, stderr = execute(
       'account',
       'create-account',
-      'sponsor-by-faucet-service', new_account_id,
-      'use-manually-provided-public-key', public_key,
+      'sponsor-by-faucet-service', new_account.to_s,
+      *case public_key
+        when nil then ['autogenerate-new-keypair', 'save-to-keychain']
+        when String then ['use-manually-provided-public-key', public_key]
+        when Array then public_key
+        else raise ArgumentError
+      end,
       'network-config', @network,
       'create'
     )
@@ -88,16 +93,22 @@ module NEAR::CLI::Account
   ##
   # Creates a new account funded by another account.
   #
-  # @param [NEAR::Account] new_account
-  # @param [NEAR::Account] signer Account that signs & funds the transaction
-  # @param [NEAR::Balance] deposit Amount of NEAR to attach
+  # @param [NEAR::Account, #to_s] new_account
+  # @param [NEAR::Account, #to_s] signer Account that signs & funds the transaction
+  # @param [String, nil] public_key
+  # @param [NEAR::Balance, #to_s] deposit Amount of NEAR to attach
   # @return [String]
-  def create_account_with_funding(new_account, signer:, deposit: nil)
+  def create_account_with_funding(new_account, signer:, public_key: nil, deposit: nil)
     stdout, stderr = execute(
       'account',
       'create-account',
       'fund-myself', new_account.to_s, (deposit ? deposit.to_s : '0') + ' NEAR',
-      'autogenerate-new-keypair', 'save-to-keychain',
+      *case public_key
+        when nil then ['autogenerate-new-keypair', 'save-to-keychain']
+        when String then ['use-manually-provided-public-key', public_key]
+        when Array then public_key
+        else raise ArgumentError
+      end,
       'sign-as', signer.to_s,
       'network-config', @network,
       'sign-with-keychain',

data/lib/near/error.rb

@@ -0,0 +1,18 @@
+# This is free and unencumbered software released into the public domain.
+
+class NEAR::Error < StandardError
+  class InvalidBlock < NEAR::Error
+    def initialize(block_height = nil)
+      @block_height = block_height.to_i if block_height
+      super(block_height ?
+        "Block height ##{block_height.to_i} does not exist" :
+        "Block height does not exist")
+    end
+
+    attr_reader :block_height
+  end # NEAR::Error::InvalidBlock
+
+  class TemporaryProblem < NEAR::Error; end
+
+  class UnexpectedProblem < NEAR::Error; end
+end # NEAR::Error

data/lib/near/network.rb

@@ -1,6 +1,10 @@
 # This is free and unencumbered software released into the public domain.
 
-require 'net/http'
+require 'faraday'
+require 'faraday/follow_redirects'
+require 'faraday/retry'
+
+require_relative 'error'
 
 ##
 # Represents a NEAR Protocol network.
@@ -24,20 +28,107 @@ class NEAR::Network
     self.class.const_get(:NEARDATA_URL)
   end
 
+  ##
+  # Fetches a block range.
+  #
+  # The block data is fetched from the neardata.xyz API.
+  #
+  # @param [NEAR::Block, #to_i] from
+  # @param [NEAR::Block, #to_i] to
+  # @yield [NEAR::Block]
+  # @yieldparam [NEAR::Block] block
+  # @yieldreturn [void]
+  # @return [Enumerator]
+  def fetch_blocks(from: nil, to: nil, &)
+    return enum_for(:fetch_blocks) unless block_given?
+    from = self.fetch_latest.height unless from
+    from, to = from.to_i, to&.to_i
+    (from..to).each do |block_height|
+      yield self.fetch(block_height)
+    end
+  end
+
   ##
   # Fetches the block at the given height.
   #
   # The block data is fetched from the neardata.xyz API.
-  # If the block does not exist, `nil` is returned.
   #
   # @param [NEAR::Block, #to_i] block
-  # @return [Object]
+  # @return [NEAR::Block]
+  # @raise [NEAR::Error::InvalidBlock] if the block does not exist
   def fetch(block)
-    response = Net::HTTP.get_response(URI("#{neardata_url}/v0/block/#{block.to_i}"))
-    case response
-      when Net::HTTPSuccess then JSON.parse(response.body)
-      when Net::HTTPNotFound then nil
-      else raise response.to_s
+    self.fetch_neardata_block(block.to_i)
+  end
+
+  ##
+  # Fetches the latest finalized block.
+  #
+  # The block data is fetched from the neardata.xyz API.
+  # The block is guaranteed to exist.
+  #
+  # @return [NEAR::Block]
+  def fetch_latest
+    self.fetch_neardata_block(:final)
+  end
+
+  protected
+
+  ##
+  # @param [Integer, Symbol] block_id
+  # @return [NEAR::Block]
+  def fetch_neardata_block(block_id)
+    request_path = case block_id
+      when Integer then "/v0/block/#{block_id}"
+      when Symbol then "/v0/last_block/#{block_id}"
+      else raise ArgumentError
+    end
+
+    begin
+      block_data = self.fetch_neardata_url(request_path)
+    rescue Faraday::ResourceNotFound => error
+      case error.response[:body]['type']
+        when "BLOCK_DOES_NOT_EXIST", "BLOCK_HEIGHT_TOO_LOW", "BLOCK_HEIGHT_TOO_HIGH"
+          raise NEAR::Error::InvalidBlock, block_id
+        else raise NEAR::Error::UnexpectedProblem
+      end
+    end
+
+    return nil if block_data.nil? || block_data == 'null'
+    block_header = block_data['block']['header']
+    block_height = block_header['height'].to_i
+    block_hash = block_header['hash'].to_s
+    NEAR::Block.new(height: block_height, hash: block_hash, data: block_data)
+  end
+
+  ##
+  # @return [Object]
+  def fetch_neardata_url(path)
+    begin
+      retries ||= 0
+      self.http_client.get("#{neardata_url}#{path}").body
+    rescue Faraday::ConnectionFailed => error
+      # `Faraday::Retry` doesn't seem able to handle `ConnectionFailed`,
+      # so we'll handle it manually here. Note that in case of a DNS error,
+      # there's no point in retrying, so we'll wrap & re-raise the error.
+      case error.wrapped_exception
+        when Socket::ResolutionError then raise NEAR::Error::TemporaryProblem
+        else retry if (retries += 1) < 3
+      end
+      raise NEAR::Error::UnexpectedProblem
+    end
+  end
+
+  ##
+  # @return [Faraday::Connection]
+  def http_client
+    Faraday.new do |faraday|
+      faraday.response :raise_error
+      faraday.response :follow_redirects
+      faraday.response :json
+      faraday.request :retry, {
+        max: 3,
+        exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Faraday::ConnectionFailed]
+      }.freeze
     end
   end
 end # NEAR::Testnet

data/lib/near/transaction.rb

@@ -3,10 +3,21 @@
 ##
 # Represents a NEAR transaction.
 class NEAR::Transaction
+  ##
+  # @param [Hash] json
+  # @return [NEAR::Transaction]
+  def self.parse(json)
+    tx_data = json['transaction']
+    NEAR::Transaction.new(tx_data['hash'], data: tx_data)
+  end
+
   ##
   # @param [String, #to_s] hash
-  def initialize(hash)
+  # @param [Hash, #to_h] data
+  # @return [void]
+  def initialize(hash, data: nil)
     @hash = hash.to_s
+    @data = data.to_h if data
   end
 
   ##
@@ -15,7 +26,108 @@ class NEAR::Transaction
   # @return [String]
   attr_reader :hash
 
+  ##
+  # The transaction data, if available.
+  #
+  # @return [Hash]
+  attr_reader :data
+
+  ##
+  # The transaction signer account.
+  #
+  # @return [NEAR::Account]
+  attr_reader :signer
+  def signer
+    @signer ||= NEAR::Account.new(self.signer_id)
+  end
+
+  ##
+  # The transaction signer ID.
+  #
+  # @return [String]
+  attr_reader :signer_id
+  def signer_id
+    self.data['signer_id']
+  end
+
+  ##
+  # The transaction receiver account.
+  #
+  # @return [NEAR::Account]
+  attr_reader :receiver
+  def receiver
+    @receiver ||= NEAR::Account.new(self.receiver_id)
+  end
+
+  ##
+  # The transaction receiver ID.
+  #
+  # @return [String]
+  attr_reader :receiver_id
+  def receiver_id
+    self.data['receiver_id']
+  end
+
+  ##
+  # @return [String]
+  attr_reader :public_key
+  def public_key
+    self.data['public_key']
+  end
+
+  ##
+  # @return [String]
+  attr_reader :signature
+  def signature
+    self.data['signature']
+  end
+
+  ##
+  # @return [Integer]
+  attr_reader :nonce
+  def nonce
+    self.data['nonce']
+  end
+
+  ##
+  # @return [Integer]
+  attr_reader :priority_fee
+  def priority_fee
+    self.data['priority_fee']
+  end
+
+  ##
+  # The transaction actions.
+  #
+  # @return [Array<Hash>]
+  attr_reader :actions
+  def actions
+    self.data['actions']
+  end
+
+  ##
+  # @yield [NEAR::Action]
+  # @yieldparam [NEAR::Action] action
+  # @yieldreturn [void]
+  # @return [Enumerator] if no block is given
+  def each_action(&)
+    return enum_for(:each_action) unless block_given?
+    self.data['actions'].each do |action|
+      yield NEAR::Action.parse(action)
+    end
+  end
+
   ##
   # @return [String]
   def to_s; @hash; end
+
+  ##
+  # @return [Hash]
+  def to_h; @data; end
+
+  ##
+  # @return [String]
+  def inspect
+    "#<#{self.class.name} hash: #{@hash.inspect}, signer: #{self.signer}, receiver: #{self.receiver}, actions: #{self.actions.size}>"
+  end
 end # NEAR::Transaction

data/lib/near.rb

@@ -3,9 +3,11 @@
 module NEAR; end
 
 require_relative 'near/account'
+require_relative 'near/action'
 require_relative 'near/balance'
 require_relative 'near/block'
 require_relative 'near/cli'
+require_relative 'near/error'
 require_relative 'near/mainnet'
 require_relative 'near/network'
 require_relative 'near/testnet'

metadata

@@ -1,14 +1,84 @@
 --- !ruby/object:Gem::Specification
 name: near
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Arto Bendiken
 bindir: bin
 cert_chain: []
-date: 2025-01-29 00:00:00.000000000 Z
+date: 2025-02-05 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.12'
+- !ruby/object:Gem::Dependency
+  name: faraday-follow_redirects
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -50,6 +120,7 @@ files:
 - VERSION
 - lib/near.rb
 - lib/near/account.rb
+- lib/near/action.rb
 - lib/near/balance.rb
 - lib/near/block.rb
 - lib/near/cli.rb
@@ -59,6 +130,7 @@ files:
 - lib/near/cli/staking.rb
 - lib/near/cli/tokens.rb
 - lib/near/cli/transaction.rb
+- lib/near/error.rb
 - lib/near/mainnet.rb
 - lib/near/network.rb
 - lib/near/testnet.rb
@@ -87,7 +159,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.3
 specification_version: 4
 summary: 'NEAR.rb: NEAR for Ruby'
 test_files: []