near 0.1.0

data/lib/near/cli/contract.rb

@@ -0,0 +1,158 @@
+# This is free and unencumbered software released into the public domain.
+
+##
+# @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 [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)
+    stdout, _ = execute(
+      'contract',
+      'call-function',
+      'as-read-only', contract_id, method_name,
+      'json-args', args.to_json,
+      'network-config', @network,
+      *block_args(block)
+    )
+    stdout
+  end
+
+  ##
+  # Calls a state-changing method on a contract.
+  #
+  # @param [String] contract_id
+  # @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
+  # @return [String] Transaction result
+  def call_function(contract_id, method_name, args = {}, signer_id:, deposit: '0 NEAR', gas: '30 TGas')
+    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,
+      'network-config', @network,
+      'sign-with-keychain',
+      'send'
+    )
+    stderr
+  end
+  alias_method :call_method, :call_function
+
+  ##
+  # Deploys a new contract.
+  #
+  # @param [String] contract_id Account to deploy the contract to
+  # @param [String] wasm_path Path to the .wasm file
+  # @param [String] signer_id Account that signs the transaction
+  # @param [String, nil] init_method Method to call after deployment
+  # @param [Hash] init_args Arguments for the init method
+  # @param [String] init_deposit Deposit for the init method
+  # @param [String] init_gas Gas for the init method
+  # @return [String] Transaction result
+  def deploy_contract(contract_id, wasm_path, signer_id:, init_method: nil, init_args: {},
+                     init_deposit: '0 NEAR', init_gas: '30 TGas')
+    args = [
+      'contract',
+      'deploy',
+      contract_id,
+      'use-file', wasm_path
+    ]
+
+    if init_method
+      args += [
+        'with-init-call', init_method,
+        'json-args', init_args.to_json,
+        'prepaid-gas', init_gas,
+        'attached-deposit', init_deposit
+      ]
+    end
+
+    args += [
+      'sign-as', signer_id,
+      'network-config', @network,
+      'sign-with-keychain',
+      'send'
+    ]
+
+    stdout, stderr = execute(*args)
+    stderr
+  end
+
+  ##
+  # Downloads a contract's WASM code.
+  #
+  # @param [String] contract_id
+  # @param [String] output_path Path to write the .wasm file to
+  # @param [Block, Integer, String, Symbol] block
+  # @return [String] Path to downloaded file
+  def download_wasm(contract_id, output_path, block: :now)
+    _, _ = execute(
+      'contract',
+      'download-wasm', contract_id,
+      'save-to-file', output_path,
+      'network-config', @network,
+      *block_args(block)
+    )
+    output_path
+  end
+
+  ##
+  # Views contract storage state with JSON formatting.
+  #
+  # @param [String] contract_id
+  # @param [String, nil] prefix Filter keys by prefix
+  # @param [Block, Integer, String, Symbol] block
+  # @return [String] Contract storage state
+  def view_storage(contract_id, prefix: nil, block: :now)
+    args = [
+      'contract',
+      'view-storage', contract_id
+    ]
+
+    args += if prefix
+      ['keys-start-with-string', prefix]
+    else
+      ['all']
+    end
+
+    args += [
+      'as-json',
+      'network-config', @network,
+      *block_args(block)
+    ]
+
+    stdout, _ = execute(*args)
+    stdout
+  end
+
+  ##
+  # Views contract storage state with base64 key filtering.
+  #
+  # @param [String] contract_id
+  # @param [String] base64_prefix Filter keys by base64 prefix
+  # @param [Block, Integer, String, Symbol] block
+  # @return [String] Contract storage state
+  def view_storage_base64(contract_id, base64_prefix, block: :now)
+    stdout, _ = execute(
+      'contract',
+      'view-storage', contract_id,
+      'keys-start-with-bytes-as-base64', base64_prefix,
+      'as-json',
+      'network-config', @network,
+      *block_args(block)
+    )
+    stdout
+  end
+end # NEAR::CLI::Contract

data/lib/near/cli/staking.rb

@@ -0,0 +1,7 @@
+# This is free and unencumbered software released into the public domain.
+
+##
+# @see https://github.com/near/near-cli-rs/blob/main/docs/GUIDE.en.md#staking---Manage-staking-view-add-and-withdraw-stake
+module NEAR::CLI::Staking
+  # TODO: implement the `NEAR::CLI::Staking` module.
+end # NEAR::CLI::Staking

data/lib/near/cli/tokens.rb

@@ -0,0 +1,70 @@
+# This is free and unencumbered software released into the public domain.
+
+##
+# @see https://github.com/near/near-cli-rs/blob/main/docs/GUIDE.en.md#tokens---Manage-token-assets-such-as-NEAR-FT-NFT
+module NEAR::CLI::Tokens
+  ##
+  # Sends NEAR tokens from one account to another.
+  #
+  # @param [String] sender_id The account sending the tokens
+  # @param [String] receiver_id The account receiving the tokens
+  # @param [NEAR::Balance] amount The amount to send
+  # @return [Hash] Transaction result
+  def send_near(sender_id, receiver_id, amount)
+    raise ArgumentError, "amount must be a NEAR::Balance" unless amount.is_a?(NEAR::Balance)
+
+    _, stderr = execute(
+      'tokens',
+      sender_id,
+      'send-near', receiver_id, amount.to_cli_arg,
+      'network-config', @network,
+      'sign-with-keychain',
+      'send'
+    )
+
+    # Extract transaction details from stderr:
+    if stderr.include?('Transaction sent')
+      tx_match = stderr.match(/Transaction ID: ([A-Za-z0-9]+)/)
+      tx_id = tx_match ? tx_match[1] : nil
+      {
+        success: true,
+        transaction_id: tx_id,
+        message: stderr.strip
+      }
+    else
+      {
+        success: false,
+        message: stderr.strip
+      }
+    end
+  end
+
+  ##
+  # Views the NEAR token balance of an account.
+  #
+  # @param [String] account_id The account to check
+  # @param [Block, Integer, String, Symbol] block The block to query (default: :now)
+  # @return [Hash] Balance information including available and total balance
+  def view_near_balance(account_id, block: :now)
+    _, stderr = execute(
+      'tokens',
+      account_id,
+      'view-near-balance',
+      'network-config', @network,
+      *block_args(block)
+    )
+
+    # Parse the balance information from stderr:
+    available_match = stderr.match(/(\d+\.?\d*) NEAR available for transfer/)
+    total_match = stderr.match(/total balance is (\d+\.?\d*) NEAR/)
+    locked_match = stderr.match(/(\d+\.?\d*) NEAR is locked/)
+
+    {
+      account_id: account_id,
+      available_balance: available_match ? NEAR::Balance.from_near(available_match[1]) : nil,
+      total_balance: total_match ? NEAR::Balance.from_near(total_match[1]) : nil,
+      locked_balance: locked_match ? NEAR::Balance.from_near(locked_match[1]) : nil,
+      block: block,
+    }
+  end
+end # NEAR::CLI::Tokens

data/lib/near/cli/transaction.rb

@@ -0,0 +1,252 @@
+# This is free and unencumbered software released into the public domain.
+
+##
+# @see https://github.com/near/near-cli-rs/blob/main/docs/GUIDE.en.md#transaction---Operate-transactions
+module NEAR::CLI::Transaction
+  ##
+  # Views status of a transaction.
+  #
+  # @param [String] tx_hash The transaction hash
+  # @return [Hash] Transaction status and details
+  def view_status(tx_hash)
+    stdout, _ = execute(
+      'transaction',
+      'view-status', tx_hash,
+      'network-config', @network
+    )
+
+    # Parse the transaction details from the output
+    parse_transaction_status(stdout)
+  end
+
+  ##
+  # Reconstructs a CLI command from an existing transaction.
+  #
+  # @param [String] tx_hash The transaction hash
+  # @return [Hash] The reconstructed transaction details and CLI command
+  def reconstruct_transaction(tx_hash)
+    stdout, _ = execute(
+      'transaction',
+      'reconstruct-transaction', tx_hash,
+      'network-config', @network
+    )
+
+    {
+      transaction: parse_transaction_reconstruction(stdout),
+      cli_command: extract_cli_command(stdout)
+    }
+  end
+
+  ##
+  # Constructs a new transaction with multiple actions.
+  #
+  # @param [String] signer_id Account that signs the transaction
+  # @param [String] receiver_id Account that receives the transaction
+  # @param [Array<Hash>] actions Array of action hashes, each containing :type and :args
+  # @return [String] Base64-encoded unsigned transaction
+  def construct_transaction(signer_id, receiver_id, actions)
+    args = [
+      'transaction',
+      'construct-transaction',
+      signer_id,
+      receiver_id
+    ]
+
+    actions.each do |action|
+      args += construct_action_args(action)
+    end
+
+    args += [
+      'network-config', @network
+    ]
+
+    stdout, _ = execute(*args)
+    extract_unsigned_transaction(stdout)
+  end
+
+  ##
+  # Signs a previously prepared unsigned transaction.
+  #
+  # @param [String] unsigned_tx Base64-encoded unsigned transaction
+  # @param [Hash] options Signing options (e.g., :keychain, :ledger, :private_key)
+  # @return [String] Base64-encoded signed transaction
+  def sign_transaction(unsigned_tx, options = {})
+    args = [
+      'transaction',
+      'sign-transaction',
+      unsigned_tx,
+      'network-config', @network
+    ]
+
+    args += case options[:method]
+    when :keychain
+      ['sign-with-keychain']
+    when :ledger
+      ['sign-with-ledger']
+    when :private_key
+      [
+        'sign-with-plaintext-private-key',
+        options[:private_key]
+      ]
+    else
+      raise ArgumentError, "Invalid signing method: #{options[:method]}"
+    end
+
+    stdout, _ = execute(*args)
+    extract_signed_transaction(stdout)
+  end
+
+  ##
+  # Sends a signed transaction.
+  #
+  # @param [String] signed_tx Base64-encoded signed transaction
+  # @return [Hash] Transaction result
+  def send_signed_transaction(signed_tx)
+    stdout, stderr = execute(
+      'transaction',
+      'send-signed-transaction',
+      signed_tx,
+      'network-config', @network
+    )
+
+    parse_transaction_result(stderr)
+  end
+
+  ##
+  # Sends a meta transaction (relayed transaction).
+  #
+  # @param [String] signed_tx Base64-encoded signed transaction
+  # @return [Hash] Transaction result
+  def send_meta_transaction(signed_tx)
+    stdout, stderr = execute(
+      'transaction',
+      'send-meta-transaction',
+      signed_tx,
+      'network-config', @network
+    )
+
+    parse_transaction_result(stderr)
+  end
+
+  private
+
+  def parse_transaction_status(output)
+    # Parse the detailed transaction status output
+    # This would need to handle all the various fields from the transaction status
+    {
+      status: extract_status(output),
+      receipts: extract_receipts(output),
+      outcome: extract_outcome(output)
+    }
+  end
+
+  def parse_transaction_reconstruction(output)
+    # Parse the transaction reconstruction output
+    {
+      signer_id: extract_signer(output),
+      receiver_id: extract_receiver(output),
+      actions: extract_actions(output)
+    }
+  end
+
+  def construct_action_args(action)
+    case action[:type]
+    when :create_account
+      ['add-action', 'create-account']
+    when :transfer
+      ['add-action', 'transfer', action[:args][:amount].to_cli_arg]
+    when :add_key
+      construct_add_key_args(action[:args])
+    when :delete_key
+      ['add-action', 'delete-key', action[:args][:public_key]]
+    when :deploy
+      ['add-action', 'deploy', action[:args][:code_path]]
+    when :function_call
+      [
+        'add-action', 'function-call',
+        action[:args][:method_name],
+        'json-args', action[:args][:args].to_json,
+        '--prepaid-gas', action[:args][:gas],
+        '--attached-deposit', action[:args][:deposit].to_cli_arg
+      ]
+    else
+      raise ArgumentError, "Unknown action type: #{action[:type]}"
+    end
+  end
+
+  def construct_add_key_args(args)
+    base_args = ['add-action', 'add-key']
+
+    if args[:permission] == :full_access
+      base_args + ['grant-full-access']
+    else
+      base_args + [
+        'grant-function-call-access',
+        '--allowance', args[:allowance].to_cli_arg,
+        '--receiver-account-id', args[:receiver_id],
+        '--method-names', Array(args[:method_names]).join(',')
+      ]
+    end + [
+      'use-manually-provided-public-key', args[:public_key]
+    ]
+  end
+
+  def parse_transaction_result(output)
+    {
+      success: output.include?('Transaction sent'),
+      transaction_id: extract_transaction_id(output),
+      message: output
+    }
+  end
+
+  def extract_unsigned_transaction(output)
+    # Extract the base64 unsigned transaction from output
+    output[/Unsigned transaction: ([A-Za-z0-9+\/=]+)/, 1]
+  end
+
+  def extract_signed_transaction(output)
+    # Extract the base64 signed transaction from output
+    output[/Signed transaction: ([A-Za-z0-9+\/=]+)/, 1]
+  end
+
+  def extract_transaction_id(output)
+    output[/Transaction ID: ([A-Za-z0-9]+)/, 1]
+  end
+
+  def extract_cli_command(output)
+    output[/Here is your console command[^\n]*\n\s*(near.+)$/, 1]
+  end
+
+  # Additional helper methods for parsing transaction status output
+  def extract_status(output)
+    # Extract status from transaction status output
+  end
+
+  def extract_receipts(output)
+    # Extract receipts from transaction status output
+  end
+
+  def extract_outcome(output)
+    # Extract outcome from transaction status output
+  end
+
+  def extract_signer(output)
+    output[/signer_id:\s+(\S+)/, 1]
+  end
+
+  def extract_receiver(output)
+    output[/receiver_id:\s+(\S+)/, 1]
+  end
+
+  def extract_actions(output)
+    # Extract and parse actions list from output
+    actions = []
+    output.scan(/-- ([^:]+):\s+(.+)$/) do |type, details|
+      actions << {
+        type: type.strip.downcase.to_sym,
+        details: details.strip
+      }
+    end
+    actions
+  end
+end # NEAR::CLI::Transaction

data/lib/near/cli.rb

@@ -0,0 +1,87 @@
+# This is free and unencumbered software released into the public domain.
+
+require 'json'
+require 'open3'
+
+require_relative 'block'
+
+class NEAR::CLI; end
+
+require_relative 'cli/account'
+require_relative 'cli/config'
+require_relative 'cli/contract'
+require_relative 'cli/staking'
+require_relative 'cli/tokens'
+require_relative 'cli/transaction'
+
+class NEAR::CLI
+  NEAR_ENV = ENV['NEAR_ENV'] || 'testnet'
+
+  class Error < StandardError; end
+  class ProgramNotFoundError < Error; end
+  class ExecutionError < Error; end
+
+  def self.find_program
+    # First, check `$HOME/.cargo/bin/near`:
+    path = File.expand_path('~/.cargo/bin/near')
+    return path if File.executable?(path)
+
+    # Next, check `$PATH`:
+    ENV['PATH'].split(File::PATH_SEPARATOR).each do |path|
+      path = File.join(path, 'near')
+      return path if File.executable?(path)
+    end
+
+    raise ProgramNotFoundError
+  end
+
+  ##
+  # @param [String, #to_s] path
+  # @param [String, #to_s] network
+  def initialize(path: self.class.find_program, network: NEAR_ENV)
+    @path, @network = path.to_s, network.to_s
+  end
+
+  ##
+  # @return [String]
+  def version
+    self.execute('--version').first.strip
+  end
+
+  include NEAR::CLI::Account
+  include NEAR::CLI::Tokens
+  include NEAR::CLI::Staking
+  include NEAR::CLI::Contract
+  include NEAR::CLI::Transaction
+  include NEAR::CLI::Config
+
+  private
+
+  ##
+  # @param [Array<String>] args
+  # @return [Array<String>]
+  def execute(*args)
+    command = [@path, *args.map(&:to_s)]
+    puts command.join(' ') if false
+    stdout, stderr, status = Open3.capture3(*command)
+
+    if status.success?
+      [stdout.strip, stderr.strip]
+    else
+      raise ExecutionError, "Command `#{command.join(' ')}` failed with exit code #{status.exitstatus}: #{stderr.strip}"
+    end
+  end
+
+  ##
+  # @param [Block, Integer, String, Symbol] block
+  def block_args(block)
+    block = case block
+      when :now then return ['now']
+      when NEAR::Block then block
+      when Integer then NEAR::Block.at_height(block)
+      when String then NEAR::Block.at_hash(block)
+      else raise "invalid block specifier: #{block.inspect}"
+    end
+    block.to_cli_args
+  end
+end # NEAR::CLI

data/lib/near/transaction.rb

@@ -0,0 +1,21 @@
+# This is free and unencumbered software released into the public domain.
+
+##
+# Represents a NEAR transaction.
+class NEAR::Transaction
+  ##
+  # @param [String, #to_s] hash
+  def initialize(hash)
+    @hash = hash.to_s
+  end
+
+  ##
+  # The transaction hash.
+  #
+  # @return [String]
+  attr_reader :hash
+
+  ##
+  # @return [String]
+  def to_s; @hash; end
+end # NEAR::Transaction

data/lib/near/version.rb

@@ -0,0 +1 @@
+# This is free and unencumbered software released into the public domain.

data/lib/near.rb

@@ -0,0 +1,10 @@
+# This is free and unencumbered software released into the public domain.
+
+module NEAR; end
+
+require_relative 'near/account'
+require_relative 'near/balance'
+require_relative 'near/block'
+require_relative 'near/cli'
+require_relative 'near/transaction'
+require_relative 'near/version'

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: near
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Arto Bendiken
+bindir: bin
+cert_chain: []
+date: 2025-01-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A Ruby client library for the NEAR Protocol.
+email: arto@bendiken.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AUTHORS
+- CHANGES.md
+- README.md
+- UNLICENSE
+- VERSION
+- lib/near.rb
+- lib/near/account.rb
+- lib/near/balance.rb
+- lib/near/block.rb
+- lib/near/cli.rb
+- lib/near/cli/account.rb
+- lib/near/cli/config.rb
+- lib/near/cli/contract.rb
+- lib/near/cli/staking.rb
+- lib/near/cli/tokens.rb
+- lib/near/cli/transaction.rb
+- lib/near/transaction.rb
+- lib/near/version.rb
+homepage: https://github.com/dryruby/near.rb
+licenses:
+- Unlicense
+metadata:
+  bug_tracker_uri: https://github.com/dryruby/near.rb/issues
+  changelog_uri: https://github.com/dryruby/near.rb/blob/master/CHANGES.md
+  documentation_uri: https://rubydoc.info/gems/near
+  homepage_uri: https://github.com/dryruby/near.rb
+  source_code_uri: https://github.com/dryruby/near.rb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: 'NEAR.rb: NEAR for Ruby'
+test_files: []