near 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ab3d2b8796c8b9d6db6d842a843882a02b1497070454e67dda41a2105dbe7aa
+  data.tar.gz: 66de38abb9b8bd7162116f110ae2a3f81412f7e580bb2e479db5133d2504f725
+SHA512:
+  metadata.gz: 8cead3d3f26398a34925d6ba326c981f19be8e4324348f7dd8879a1c291ad11bd80080c11023477e3f4ee5bbfcf5bddfc421e85bea05f8e42acfd672e28bea0f
+  data.tar.gz: f11b1a7a3c795865375feb3c873e9158009b6508a06150d91b3dff126b074920b2c91e658c6bc121e91098f64c198e47aaff0a7ee1348adb1e39364212eb2db5

data/AUTHORS

@@ -0,0 +1 @@
+* Arto Bendiken <arto@bendiken.net>

data/CHANGES.md

@@ -0,0 +1,10 @@
+# Changelog
+
+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.1.0 - 2025-01-19
+
+## 0.0.0 - 2025-01-11

data/README.md

@@ -0,0 +1,232 @@
+# NEAR.rb: NEAR for Ruby
+
+[![License](https://img.shields.io/badge/license-Public%20Domain-blue.svg)](https://unlicense.org)
+[![Compatibility](https://img.shields.io/badge/ruby-3.0%2B-blue)](https://rubygems.org/gems/near)
+[![Package](https://img.shields.io/gem/v/near)](https://rubygems.org/gems/near)
+[![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.
+
+## ✨ Features
+
+- Wraps the complete CLI features in an idiomatic Ruby interface.
+- Provides comprehensive account management operations.
+- Supports token operations for NEAR and other assets.
+- Supports smart contract deployment and interaction.
+- Handles transaction construction, signing, and monitoring.
+- Integrates with hardware wallets and secure key storage.
+- Implements type-safe balance operations and input validation.
+- 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+
+- [Ruby] 3.0+
+
+## ⬇️ Installation
+
+### Installation via RubyGems
+
+```bash
+gem install near
+```
+
+## 👉 Examples
+
+### Importing the library
+
+```ruby
+require 'near'
+
+# Use the NEAR testnet (the default):
+testnet = NEAR::CLI.new(network: 'testnet')
+
+# Use the NEAR mainnet (to test in prod):
+# mainnet = NEAR::CLI.new(network: 'mainnet')
+```
+
+### Viewing account details
+
+```ruby
+# View an account summary:
+summary = testnet.view_account_summary('arto.testnet')
+puts summary
+
+# View an account at a specific block height:
+summary = testnet.view_account_summary('arto.testnet',
+  block: 185_304_186
+)
+
+# View an account at a specific block hash:
+summary = testnet.view_account_summary('arto.testnet',
+  block: '13UmYhdcdst88aC19QhjYjNMF1zRmaAyY6iqwc5q45bx'
+)
+
+# List access keys in an account:
+keys = testnet.list_keys('arto.testnet')
+puts keys
+```
+
+### Importing accounts
+
+```ruby
+# Import an account using a seed phrase:
+result = testnet.import_account_with_seed_phrase(
+  'rapid cover napkin accuse junk drill sick tooth poem patch evil fan',
+  hd_path: "m/44'/397'/0'"
+)
+
+# Import an account using a private key:
+result = testnet.import_account_with_private_key(
+  'ed25519:5YhAaEe3G4VtiBavJMvpzPPmknfsTauzVjwK1ZjPVw2MFM6zFyUv4tSiSfCbCn78mEnMifE6iX5qbhFsWEwErcC2'
+)
+```
+
+### Creating accounts
+
+```ruby
+# Create an account funded from a faucet (testnet only):
+result = testnet.create_account_with_faucet(
+  'mynewaccount.testnet',
+  'ed25519:HVPgAsZkZ7cwLZDqK313XJsDyqAvgBxrATcD7VacA8KE'
+)
+
+# Create an account funded by another account:
+result = testnet.create_account_with_funding(
+  'sub.example.testnet',           # new account
+  'example.testnet',               # funding account
+  'ed25519:6jm8hWUgwoEeGmpdEyk9zrCqtXM8kHhvg8M236ZaGusS',  # public key
+  '1 NEAR'                         # initial deposit
+)
+
+# Create a new implicit account:
+result = testnet.create_implicit_account('/path/to/credentials/folder')
+```
+
+### Deleting accounts
+
+```ruby
+# Delete an existing account:
+result = testnet.delete_account(
+  'todelete.testnet',     # account to delete
+  'beneficiary.testnet'   # account receiving remaining balance
+)
+```
+
+### Managing access keys
+
+```ruby
+# Add a full-access key to an account:
+result = testnet.add_full_access_key(
+  'myaccount.testnet',
+  'ed25519:75a5ZgVZ9DFTxs4THtFxPtLj7AY3YzpxtapTQBdcMXx3'
+)
+
+# Add a function-call key to an account:
+result = testnet.add_function_call_key(
+  'myaccount.testnet',
+  'ed25519:27R66L6yevyHbsk4fESZDC8QUQBwCdx6vvkk1uQmG7NY',
+  'app.example.testnet',           # contract that can be called
+  ['set_status', 'get_status'],    # allowed methods
+  '1 NEAR'                         # allowance
+)
+
+# Delete an access key from an account:
+result = testnet.delete_key(
+  'myaccount.testnet',
+  'ed25519:75a5ZgVZ9DFTxs4THtFxPtLj7AY3YzpxtapTQBdcMXx3'
+)
+```
+
+### Managing tokens
+
+```ruby
+# Send NEAR tokens from one account to another:
+result = testnet.send_near(
+  'mysender.testnet',
+  'myreceiver.testnet',
+  NEAR::Balance.new('0.1')
+)
+```
+
+### Calling read-only contract methods
+
+```ruby
+# Call a view method:
+result = testnet.view_call(
+  'myapp.testnet',                # contract account
+  'get_status',                   # method name
+  { account_id: 'user.testnet' }  # arguments
+)
+
+# Call a view method at a specific block height:
+result = testnet.view_call(
+  'myapp.testnet',
+  'get_status',
+  { account_id: 'user.testnet' },
+  block: 12345678
+)
+```
+
+### Calling mutative contract methods
+
+```ruby
+# Call a mutative method as a transaction:
+result = testnet.call_function(
+  'myapp.testnet',            # contract account
+  'set_status',               # method name
+  { status: 'Hello NEAR!' },  # arguments
+  signer_id: 'user.testnet',  # account that signs tx
+  deposit: '1 NEAR',          # attached deposit
+  gas: '30 TGas'              # attached gas
+)
+```
+
+### Deploying a smart contract
+
+```ruby
+# Deploy a new contract:
+result = testnet.deploy_contract(
+  'myapp.testnet',            # contract account
+  '/tmp/contract.wasm',       # WASM file path
+  signer_id: 'deployer.testnet',
+  # Optional initialization:
+  init_method: 'new',
+  init_args: { owner_id: 'deployer.testnet' },
+  init_deposit: '0 NEAR',
+  init_gas: '30 TGas'
+)
+
+# Download a contract WebAssembly blob:
+result = testnet.download_wasm(
+  'myapp.testnet',
+  '/tmp/contract.wasm'
+)
+```
+
+## 📚 Reference
+
+https://rubydoc.info/gems/near
+
+## 👨‍💻 Development
+
+```bash
+git clone https://github.com/dryruby/near.rb.git
+```
+
+- - -
+
+[![Share on Twitter](https://img.shields.io/badge/share%20on-twitter-03A9F4?logo=twitter)](https://x.com/share?url=https://github.com/dryruby/near.rb&text=NEAR.rb)
+[![Share on Reddit](https://img.shields.io/badge/share%20on-reddit-red?logo=reddit)](https://reddit.com/submit?url=https://github.com/dryruby/near.rb&title=NEAR.rb)
+[![Share on Hacker News](https://img.shields.io/badge/share%20on-hacker%20news-orange?logo=ycombinator)](https://news.ycombinator.com/submitlink?u=https://github.com/dryruby/near.rb&t=NEAR.rb)
+[![Share on Facebook](https://img.shields.io/badge/share%20on-facebook-1976D2?logo=facebook)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/dryruby/near.rb)
+
+[NEAR CLI]: https://github.com/near/near-cli-rs
+[NEAR Protocol]: https://near.org
+[NEAR command-line interface]: https://docs.near.org/tools/near-cli
+[Ruby]: https://ruby-lang.org
+[mainnet]: https://docs.near.org/concepts/basics/networks#mainnet
+[testnet]: https://docs.near.org/concepts/basics/networks#testnet

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org/>

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/near/account.rb

@@ -0,0 +1,31 @@
+# This is free and unencumbered software released into the public domain.
+
+##
+# Represents a NEAR account.
+#
+# @see https://nomicon.io/DataStructures/Account
+class NEAR::Account
+  ##
+  # @param [String, #to_s] id
+  def initialize(id)
+    @id = id.to_s
+  end
+
+  ##
+  # The account name.
+  #
+  # @return [String]
+  attr_reader :id
+
+  ##
+  # The balance as a Ⓝ-prefixed string.
+  #
+  # @return [String]
+  def inspect
+    "Ⓝ#{@id}"
+  end
+
+  ##
+  # @return [String]
+  def to_s; @id; end
+end # NEAR::Block

data/lib/near/balance.rb

@@ -0,0 +1,57 @@
+# This is free and unencumbered software released into the public domain.
+
+require 'bigdecimal'
+
+##
+# Represents a NEAR balance.
+class NEAR::Balance
+  def self.from_near(s)
+    self.new(s)
+  end
+
+  ##
+  # @param [Numeric] quantity
+  # @raise [ArgumentError] if quantity is not a valid number
+  def initialize(quantity)
+    @quantity = case quantity
+      when BigDecimal then quantity
+      when Rational then quantity
+      when Integer then quantity
+      when Float then quantity
+      when String then BigDecimal(quantity)
+      else raise ArgumentError, "invalid quantity: #{quantity.inspect}"
+    end
+  end
+
+  ##
+  # The balance as a Ⓝ-prefixed string.
+  #
+  # @return [String]
+  def inspect
+    "Ⓝ#{@quantity.to_f}"
+  end
+
+  ##
+  # The balance as a string.
+  #
+  # @return [String]
+  def to_s; @quantity.to_s; end
+
+  ##
+  # The balance as a rational number.
+  #
+  # @return [Rational]
+  def to_r; @quantity.to_r; end
+
+  ##
+  # The balance as an integer.
+  #
+  # @return [Integer]
+  def to_i; @quantity.to_i; end
+
+  ##
+  # The balance as a floating-point number.
+  #
+  # @return [Float]
+  def to_f; @quantity.to_f; end
+end # NEAR::Balance

data/lib/near/block.rb

@@ -0,0 +1,59 @@
+# This is free and unencumbered software released into the public domain.
+
+##
+# Represents a NEAR block.
+class NEAR::Block
+  ##
+  # @return [NEAR::Block]
+  def self.now
+    self.new
+  end
+
+  ##
+  # @param [Integer, #to_i] height
+  # @return [NEAR::Block]
+  def self.at_height(height)
+    self.new(height: height)
+  end
+
+  ##
+  # @param [String, #to_s] hash
+  # @return [NEAR::Block]
+  def self.at_hash(hash)
+    self.new(hash: hash)
+  end
+
+  ##
+  # @param [Integer, #to_i] height
+  # @param [String, #to_s] hash
+  def initialize(height: nil, hash: nil)
+    @height = height.to_i if height
+    @hash = hash.to_s if hash
+  end
+
+  ##
+  # The height of the block.
+  #
+  # @return [Integer]
+  attr_reader :height
+
+  ##
+  # The hash of the block.
+  #
+  # @return [String]
+  attr_reader :hash
+
+  ##
+  # @return [Array<String>]
+  def to_cli_args
+    return ['at-block-height', @height] if @height
+    return ['at-block-hash', @hash] if @hash
+    ['now']
+  end
+
+  ##
+  # @return [String]
+  def to_s
+    (@height || @hash || :now).to_s
+  end
+end # NEAR::Block

data/lib/near/cli/account.rb

@@ -0,0 +1,264 @@
+# 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#account---Manage-accounts
+module NEAR::CLI::Account
+  ##
+  # Views properties for an account.
+  #
+  # @param [String] account_id
+  # @param [Block, Integer, String, Symbol] block
+  # @return [String]
+  def view_account_summary(account_id, block: :now)
+    stdout, _ = execute(
+      'account',
+      'view-account-summary', account_id,
+      'network-config', @network,
+      *block_args(block)
+    )
+    stdout
+  end
+
+  ##
+  # Lists access keys for an account.
+  #
+  # @param [String] account_id
+  # @param [Block, Integer, String, Symbol] block
+  # @return [String]
+  def list_keys(account_id, block: :now)
+    stdout, _ = execute(
+      'account',
+      'list-keys', account_id,
+      'network-config', @network,
+      *block_args(block)
+    )
+    stdout
+  end
+
+  ##
+  # Imports an existing account using a seed phrase.
+  #
+  # @param [String] seed_phrase
+  # @param [String] hd_path
+  # @return [String]
+  def import_account_with_seed_phrase(seed_phrase, hd_path: "m/44'/397'/0'")
+    _, stderr = execute(
+      'account',
+      'import-account',
+      'using-seed-phrase', seed_phrase,
+      '--seed-phrase-hd-path', hd_path,
+      'network-config', @network
+    )
+    stderr
+  end
+
+  ##
+  # Imports an existing account using a private key.
+  #
+  # @param [String] private_key
+  # @return [String]
+  def import_account_with_private_key(private_key)
+    _, stderr = execute(
+      'account',
+      'import-account',
+      'using-private-key', private_key,
+      'network-config', @network
+    )
+    stderr
+  end
+
+  ##
+  # Creates a new account sponsored by the faucet service.
+  #
+  # @param [String] new_account_id
+  # @param [String] public_key
+  # @return [String]
+  def create_account_with_faucet(new_account_id, public_key)
+    stdout, stderr = execute(
+      'account',
+      'create-account',
+      'sponsor-by-faucet-service', new_account_id,
+      'use-manually-provided-public-key', public_key,
+      'network-config', @network,
+      'create'
+    )
+    stderr
+  end
+
+  ##
+  # 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
+  # @return [String]
+  def create_account_with_funding(new_account_id, funding_account_id, public_key, deposit)
+    stdout, stderr = execute(
+      'account',
+      'create-account',
+      'fund-myself', new_account_id, deposit,
+      'use-manually-provided-public-key', public_key,
+      'sign-as', funding_account_id,
+      'network-config', @network,
+      'sign-with-keychain',
+      'send'
+    )
+    stderr
+  end
+
+  ##
+  # Creates an implicit account.
+  #
+  # @param [String] save_path
+  # @return [String]
+  def create_implicit_account(save_path)
+    stdout, stderr = execute(
+      'account',
+      'create-account',
+      'fund-later',
+      'use-auto-generation',
+      'save-to-folder', save_path
+    )
+    stderr
+  end
+
+  ##
+  # Deletes an account and transfers remaining balance to beneficiary.
+  #
+  # @param [String] account_id
+  # @param [String] beneficiary_id
+  # @return [String]
+  def delete_account(account_id, beneficiary_id)
+    stdout, stderr = execute(
+      'account',
+      'delete-account', account_id,
+      'beneficiary', beneficiary_id,
+      'network-config', @network,
+      'sign-with-keychain',
+      'send'
+    )
+    stderr
+  end
+
+  ##
+  # Adds a full access key to an account.
+  #
+  # @param [String] account_id
+  # @param [String] public_key
+  # @return [String]
+  def add_full_access_key(account_id, public_key)
+    stdout, stderr = execute(
+      'account',
+      'add-key', account_id,
+      'grant-full-access',
+      'use-manually-provided-public-key', public_key,
+      'network-config', @network,
+      'sign-with-keychain',
+      'send'
+    )
+    stderr
+  end
+
+  ##
+  # Adds a function call access key to an account.
+  #
+  # @param [String] account_id
+  # @param [String] public_key
+  # @param [String] receiver_id
+  # @param [Array<String>] method_names
+  # @param [String] allowance
+  # @return [String]
+  def add_function_call_key(account_id, public_key, receiver_id, method_names, allowance)
+    stdout, stderr = execute(
+      'account',
+      'add-key', account_id,
+      'grant-function-call-access',
+      '--allowance', allowance,
+      '--receiver-account-id', receiver_id,
+      '--method-names', method_names.join(', '),
+      'use-manually-provided-public-key', public_key,
+      'network-config', @network,
+      'sign-with-keychain',
+      'send'
+    )
+    stderr
+  end
+
+  ##
+  # Deletes an access key from an account.
+  #
+  # @param [String] account_id
+  # @param [String] public_key
+  # @return [String]
+  def delete_key(account_id, public_key)
+    stdout, stderr = execute(
+      'account',
+      'delete-key', account_id,
+      public_key,
+      'network-config', @network,
+      'sign-with-keychain',
+      'send'
+    )
+    stderr
+  end
+
+  ##
+  # Views storage balance for an account.
+  #
+  # @param [String] contract_id
+  # @param [String] account_id
+  # @param [Block, Integer, String, Symbol] block
+  # @return [String]
+  def view_storage_balance(contract_id, account_id, block: :now)
+    stdout, _ = execute(
+      'account',
+      'manage-storage-deposit', contract_id,
+      'view-balance', account_id,
+      'network-config', @network,
+      *block_args(block)
+    )
+    stdout
+  end
+
+  ##
+  # Makes a storage deposit for an account.
+  #
+  # @param [String] contract_id
+  # @param [String] account_id
+  # @param [String] deposit
+  # @param [String] sign_as
+  # @return [String]
+  def make_storage_deposit(contract_id, account_id, deposit, sign_as)
+    stdout, stderr = execute(
+      'account',
+      'manage-storage-deposit', contract_id,
+      'deposit', account_id, deposit,
+      'sign-as', sign_as,
+      'network-config', @network,
+      'sign-with-keychain',
+      'send'
+    )
+    stderr
+  end
+
+  ##
+  # Withdraws storage deposit for an account.
+  #
+  # @param [String] contract_id
+  # @param [String] amount
+  # @param [String] account_id
+  # @return [String]
+  def withdraw_storage_deposit(contract_id, amount, account_id)
+    stdout, stderr = execute(
+      'account',
+      'manage-storage-deposit', contract_id,
+      'withdraw', amount,
+      'sign-as', account_id,
+      'network-config', @network,
+      'sign-with-keychain',
+      'send'
+    )
+    stderr
+  end
+end # NEAR::CLI::Account

data/lib/near/cli/config.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#config---Manage-connections-in-a-configuration-file
+module NEAR::CLI::Config
+  # TODO: implement the `NEAR::CLI::Config` module.
+end # NEAR::CLI::Config