near 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ab3d2b8796c8b9d6db6d842a843882a02b1497070454e67dda41a2105dbe7aa
-  data.tar.gz: 66de38abb9b8bd7162116f110ae2a3f81412f7e580bb2e479db5133d2504f725
+  metadata.gz: cf5d4ecbf47a20dcb7316560abfdf3317505824ed2a501dc769e53186db46571
+  data.tar.gz: 5745b4bd4742054e9c5e710b4e267795636fd4d82c0866a3209ed804c306b25a
 SHA512:
-  metadata.gz: 8cead3d3f26398a34925d6ba326c981f19be8e4324348f7dd8879a1c291ad11bd80080c11023477e3f4ee5bbfcf5bddfc421e85bea05f8e42acfd672e28bea0f
-  data.tar.gz: f11b1a7a3c795865375feb3c873e9158009b6508a06150d91b3dff126b074920b2c91e658c6bc121e91098f64c198e47aaff0a7ee1348adb1e39364212eb2db5
+  metadata.gz: b877435cf142fab1a9d2f4b6651f1993dbf05b7c8eeea28cc76ea9ac6930a855a6570576ae5fb8012e869949efd1b56ca6cce5474bd318735996c9b8713d74f9
+  data.tar.gz: a0e57d4a298b6e52d320a9c2be9ccc8aef0f6abe7ed24e18535c6dbc0fffdbe153f3b8fa3c676cc33ac5823824d1a878175778684c88d1e272354d841ba9a388

data/CHANGES.md

@@ -5,6 +5,22 @@ 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.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

@@ -17,13 +17,14 @@ 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.17+
+- [NEAR CLI] 0.19+
 - [Ruby] 3.0+
 
 ## ⬇️ Installation
@@ -40,12 +41,26 @@ gem install near
 
 ```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)
+```
 
+### 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 +245,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.2.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/balance.rb

@@ -23,6 +23,10 @@ class NEAR::Balance
     end
   end
 
+  ##
+  # The canonical zero balance.
+  ZERO = self.new(0).freeze
+
   ##
   # The balance as a Ⓝ-prefixed string.
   #
@@ -35,7 +39,12 @@ class NEAR::Balance
   # 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

@@ -51,6 +51,12 @@ class NEAR::Block
     ['now']
   end
 
+  ##
+  # @return [Integer]
+  def to_i
+    @height
+  end
+
   ##
   # @return [String]
   def to_s

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/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,43 @@
+# This is free and unencumbered software released into the public domain.
+
+require 'net/http'
+
+##
+# 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 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]
+  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
+    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.rb

@@ -6,5 +6,22 @@ require_relative 'near/account'
 require_relative 'near/balance'
 require_relative 'near/block'
 require_relative 'near/cli'
+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,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: near
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Arto Bendiken
 bindir: bin
 cert_chain: []
-date: 2025-01-19 00:00:00.000000000 Z
+date: 2025-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -59,6 +59,9 @@ files:
 - lib/near/cli/staking.rb
 - lib/near/cli/tokens.rb
 - lib/near/cli/transaction.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