near 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ab3d2b8796c8b9d6db6d842a843882a02b1497070454e67dda41a2105dbe7aa
-  data.tar.gz: 66de38abb9b8bd7162116f110ae2a3f81412f7e580bb2e479db5133d2504f725
+  metadata.gz: 147f21ee313f56cb2e1327e8817df79796dd56fe90eff771e9057e6d7248c4f5
+  data.tar.gz: bf81f3240cb7e18c519d85696bf472b1bf2c8e56c3049aa942fe2aaae37e38f6
 SHA512:
-  metadata.gz: 8cead3d3f26398a34925d6ba326c981f19be8e4324348f7dd8879a1c291ad11bd80080c11023477e3f4ee5bbfcf5bddfc421e85bea05f8e42acfd672e28bea0f
-  data.tar.gz: f11b1a7a3c795865375feb3c873e9158009b6508a06150d91b3dff126b074920b2c91e658c6bc121e91098f64c198e47aaff0a7ee1348adb1e39364212eb2db5
+  metadata.gz: 4cfef8be7777c9dd2f2f839284581a44a0f2479f256f09e759628c21509a6d3bc9b95ad07c7e0e13a2e8c22aa5238bd826a224cdac9c6e649388bd060971569d
+  data.tar.gz: 4c5e69608fe79e7a1e0f7a9046477ea9c590d61d1ee6bf12b530054775fc26464d68ddd29c6c9655f05459faf2752a4c7119e5a29afb17a2500ba115618d0b3d

data/CHANGES.md

@@ -5,6 +5,33 @@ 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.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`
+
+### 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()`
+
+### Fixed
+- Fix the formatting of balances
+
 ## 0.1.0 - 2025-01-19
 
 ## 0.0.0 - 2025-01-11

data/README.md

@@ -6,10 +6,12 @@
 [![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 as well as wraps the
+[NEAR command-line interface] (CLI) in a usable Ruby interface.
 
 ## ✨ Features
 
+- Fetches block data from the [neardata.xyz] API.
 - Wraps the complete CLI features in an idiomatic Ruby interface.
 - Provides comprehensive account management operations.
 - Supports token operations for NEAR and other assets.
@@ -23,7 +25,7 @@ It wraps the [NEAR command-line interface] (CLI) into a Ruby interface.
 
 ## 🛠️ Prerequisites
 
-- [NEAR CLI] 0.17+
+- [NEAR CLI] 0.19+
 - [Ruby] 3.0+
 
 ## ⬇️ Installation
@@ -36,16 +38,100 @@ 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
 require 'near'
+```
+
+### Fetching block information
+
+Block data is fetched from the high-performance [neardata.xyz] API
+that caches blocks using Cloudflare's network with more than 330
+global edge locations:
+
+```ruby
+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
+
+See [`examples/monitor_all_transactions.rb`](examples/monitor_all_transactions.rb).
+
+```ruby
+NEAR.testnet.fetch_blocks do |block|
+  puts block.inspect
 
+  block.each_transaction do |transaction|
+    puts "\t" + transaction.inspect
+  end
+end
+```
+
+### Tracking chain actions
+
+See [`examples/monitor_all_actions.rb`](examples/monitor_all_actions.rb).
+
+```ruby
+NEAR.testnet.fetch_blocks do |block|
+  puts block.inspect
+
+  block.each_action do |action|
+    puts "\t" + action.inspect
+  end
+end
+```
+
+### Tracking contract interactions
+
+See [`examples/index_evm_transactions.rb`](examples/index_evm_transactions.rb).
+
+```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
+```
+
+### Instantiating the CLI wrapper
+
+```ruby
 # Use the NEAR testnet (the default):
-testnet = NEAR::CLI.new(network: 'testnet')
+testnet = NEAR::CLI.new(network: NEAR.testnet)
 
 # Use the NEAR mainnet (to test in prod):
-# mainnet = NEAR::CLI.new(network: 'mainnet')
+# mainnet = NEAR::CLI.new(network: NEAR.mainnet)
 ```
 
 ### Viewing account details
@@ -230,3 +316,4 @@ git clone https://github.com/dryruby/near.rb.git
 [Ruby]: https://ruby-lang.org
 [mainnet]: https://docs.near.org/concepts/basics/networks#mainnet
 [testnet]: https://docs.near.org/concepts/basics/networks#testnet
+[neardata.xyz]: https://neardata.xyz

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.3.0

data/lib/near/account.rb

@@ -5,12 +5,23 @@
 #
 # @see https://nomicon.io/DataStructures/Account
 class NEAR::Account
+  def self.parse(id)
+    self.new(id.to_s)
+  end
+
   ##
   # @param [String, #to_s] id
   def initialize(id)
     @id = id.to_s
   end
 
+  ##
+  # @return [NEAR::Account]
+  def parent
+    return nil unless @id.include?('.')
+    self.class.new(@id.split('.').drop(1).join('.'))
+  end
+
   ##
   # The account name.
   #

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
@@ -23,19 +27,28 @@ class NEAR::Balance
     end
   end
 
+  ##
+  # The canonical zero balance.
+  ZERO = self.new(0).freeze
+
   ##
   # The balance as a Ⓝ-prefixed string.
   #
   # @return [String]
   def inspect
-    "Ⓝ#{@quantity.to_f}"
+    "Ⓝ #{@quantity.to_f}"
   end
 
   ##
   # The balance as a string.
   #
   # @return [String]
-  def to_s; @quantity.to_s; end
+  def to_s
+    case @quantity
+      when BigDecimal then @quantity.to_s('F')
+      else @quantity.to_s
+    end
+  end
 
   ##
   # The balance as a rational number.

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
@@ -51,9 +180,38 @@ class NEAR::Block
     ['now']
   end
 
+  ##
+  # @return [Integer]
+  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

@@ -88,18 +88,17 @@ module NEAR::CLI::Account
   ##
   # Creates a new account funded by another account.
   #
-  # @param [String] new_account_id
-  # @param [String] funding_account_id
-  # @param [String] public_key
-  # @param [String] deposit
+  # @param [NEAR::Account] new_account
+  # @param [NEAR::Account] signer Account that signs & funds the transaction
+  # @param [NEAR::Balance] deposit Amount of NEAR to attach
   # @return [String]
-  def create_account_with_funding(new_account_id, funding_account_id, public_key, deposit)
+  def create_account_with_funding(new_account, signer:, deposit: nil)
     stdout, stderr = execute(
       'account',
       'create-account',
-      'fund-myself', new_account_id, deposit,
-      'use-manually-provided-public-key', public_key,
-      'sign-as', funding_account_id,
+      'fund-myself', new_account.to_s, (deposit ? deposit.to_s : '0') + ' NEAR',
+      'autogenerate-new-keypair', 'save-to-keychain',
+      'sign-as', signer.to_s,
       'network-config', @network,
       'sign-with-keychain',
       'send'
@@ -126,14 +125,15 @@ module NEAR::CLI::Account
   ##
   # Deletes an account and transfers remaining balance to beneficiary.
   #
-  # @param [String] account_id
-  # @param [String] beneficiary_id
+  # @param [NEAR::Account] account
+  # @param [NEAR::Account] beneficiary
   # @return [String]
-  def delete_account(account_id, beneficiary_id)
+  def delete_account(account, beneficiary: nil)
+    account = NEAR::Account.parse(account)
     stdout, stderr = execute(
       'account',
-      'delete-account', account_id,
-      'beneficiary', beneficiary_id,
+      'delete-account', account.to_s,
+      'beneficiary', (beneficiary || account.parent).to_s,
       'network-config', @network,
       'sign-with-keychain',
       'send'

data/lib/near/cli/contract.rb

@@ -1,21 +1,24 @@
 # This is free and unencumbered software released into the public domain.
 
+require "base64"
+require "pathname"
+
 ##
 # @see https://github.com/near/near-cli-rs/blob/main/docs/GUIDE.en.md#contract---Manage-smart-contracts-deploy-code-call-functions
 module NEAR::CLI::Contract
   ##
   # Calls a view method on a contract (read-only).
   #
-  # @param [String] contract_id
+  # @param [NEAR::Account] contract
   # @param [String] method_name
   # @param [Hash] args JSON arguments for the method
   # @param [Block, Integer, String, Symbol] block
   # @return [String] The method call result
-  def view_call(contract_id, method_name, args = {}, block: :now)
+  def view_call(contract, method_name, args = {}, block: :now)
     stdout, _ = execute(
       'contract',
       'call-function',
-      'as-read-only', contract_id, method_name,
+      'as-read-only', contract.to_s, method_name,
       'json-args', args.to_json,
       'network-config', @network,
       *block_args(block)
@@ -26,22 +29,31 @@ module NEAR::CLI::Contract
   ##
   # Calls a state-changing method on a contract.
   #
-  # @param [String] contract_id
+  # @param [NEAR::Account] contract
   # @param [String] method_name
-  # @param [Hash] args JSON arguments for the method
-  # @param [String] signer_id Account that signs the transaction
-  # @param [String] deposit Amount of NEAR to attach
-  # @param [String] gas Amount of gas to attach
+  # @param [Hash, Array, String, Pathname] args Arguments for the method
+  # @param [NEAR::Account] signer Account that signs the transaction
+  # @param [NEAR::Balance] deposit Amount of NEAR to attach
+  # @param [NEAR::Gas, #to_s] gas Amount of gas to attach
   # @return [String] Transaction result
-  def call_function(contract_id, method_name, args = {}, signer_id:, deposit: '0 NEAR', gas: '30 TGas')
+  def call_function(contract, method_name, args = {}, signer:, deposit: nil, gas: '100.0 Tgas')
+    args = case args
+      when Hash, Array then ['json-args', args.to_json]
+      when String then case
+        when args.ascii_only? then ['text-args', args]
+        else ['base64-args', Base64.strict_encode64(args)]
+      end
+      when Pathname then ['file-args', args.to_s]
+      else raise ArgumentError, "Invalid argument type: #{args.inspect}"
+    end
     stdout, stderr = execute(
       'contract',
       'call-function',
-      'as-transaction', contract_id, method_name,
-      'json-args', args.to_json,
-      'prepaid-gas', gas,
-      'attached-deposit', deposit,
-      'sign-as', signer_id,
+      'as-transaction', contract.to_s, method_name.to_s,
+      *args,
+      'prepaid-gas', gas.to_s,
+      'attached-deposit', (deposit ? deposit.to_s : '0') + ' NEAR',
+      'sign-as', signer.to_s,
       'network-config', @network,
       'sign-with-keychain',
       'send'

data/lib/near/cli.rb

@@ -22,6 +22,8 @@ class NEAR::CLI
   class ExecutionError < Error; end
 
   def self.find_program
+    return ENV['NEAR_CLI'] if ENV['NEAR_CLI']
+
     # First, check `$HOME/.cargo/bin/near`:
     path = File.expand_path('~/.cargo/bin/near')
     return path if File.executable?(path)
@@ -37,7 +39,7 @@ class NEAR::CLI
 
   ##
   # @param [String, #to_s] path
-  # @param [String, #to_s] network
+  # @param [Network, #to_s] network
   def initialize(path: self.class.find_program, network: NEAR_ENV)
     @path, @network = path.to_s, network.to_s
   end
@@ -61,6 +63,7 @@ class NEAR::CLI
   # @param [Array<String>] args
   # @return [Array<String>]
   def execute(*args)
+    #command = [@path, '--quiet', *args.map(&:to_s)] # TODO: near-cli-rs 0.19+
     command = [@path, *args.map(&:to_s)]
     puts command.join(' ') if false
     stdout, stderr, status = Open3.capture3(*command)

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

@@ -0,0 +1,17 @@
+# This is free and unencumbered software released into the public domain.
+
+require_relative 'network'
+
+##
+# Represents the NEAR Mainnet.
+#
+# @see https://docs.near.org/concepts/basics/networks#mainnet
+class NEAR::Mainnet < NEAR::Network
+  NEARDATA_URL = 'https://mainnet.neardata.xyz'.freeze
+
+  ##
+  # @return [void]
+  def initialize
+    super(:mainnet)
+  end
+end # NEAR::Mainnet

data/lib/near/network.rb

@@ -0,0 +1,134 @@
+# This is free and unencumbered software released into the public domain.
+
+require 'faraday'
+require 'faraday/follow_redirects'
+require 'faraday/retry'
+
+require_relative 'error'
+
+##
+# Represents a NEAR Protocol network.
+#
+# @see https://docs.near.org/concepts/basics/networks
+class NEAR::Network
+  ##
+  # @param [Symbol, #to_sym] id
+  # @return [void]
+  def initialize(id)
+    @id = id.to_sym
+  end
+
+  ##
+  # @return [String]
+  def to_s; @id.to_s; end
+
+  ##
+  # @return [String]
+  def neardata_url
+    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.
+  #
+  # @param [NEAR::Block, #to_i] block
+  # @return [NEAR::Block]
+  # @raise [NEAR::Error::InvalidBlock] if the block does not exist
+  def fetch(block)
+    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/testnet.rb

@@ -0,0 +1,17 @@
+# This is free and unencumbered software released into the public domain.
+
+require_relative 'network'
+
+##
+# Represents the NEAR Testnet.
+#
+# @see https://docs.near.org/concepts/basics/networks#testnet
+class NEAR::Testnet < NEAR::Network
+  NEARDATA_URL = 'https://testnet.neardata.xyz'.freeze
+
+  ##
+  # @return [void]
+  def initialize
+    super(:testnet)
+  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,8 +3,27 @@
 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'
 require_relative 'near/transaction'
 require_relative 'near/version'
+
+module NEAR
+  ##
+  # @return [NEAR::Testnet]
+  def self.testnet
+    @testnet ||= Testnet.new
+  end
+
+  ##
+  # @return [NEAR::Mainnet]
+  def self.mainnet
+    @mainnet ||= Mainnet.new
+  end
+end

metadata

@@ -1,14 +1,84 @@
 --- !ruby/object:Gem::Specification
 name: near
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Arto Bendiken
 bindir: bin
 cert_chain: []
-date: 2025-01-19 00:00:00.000000000 Z
+date: 2025-02-02 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,10 @@ 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
 - lib/near/transaction.rb
 - lib/near/version.rb
 homepage: https://github.com/dryruby/near.rb