NEAR.rb: NEAR for Ruby

NEAR.rb is a Ruby client library for the NEAR Protocol. 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.
• 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.18+
• Ruby 3.0+

⬇️ Installation

Installation via RubyGems

gem install near

👉 Examples

• Importing the library
• Fetching block information
• Tracking block production
• Tracking chain transactions
• Tracking chain actions
• Tracking contract interactions
• Instantiating the CLI wrapper
• Viewing account details
• Importing accounts
• Creating accounts
• Deleting accounts
• Managing access keys
• Managing tokens
• Calling read-only contract methods
• Calling mutative contract methods
• Deploying a smart contract

Importing the library

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:

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:

NEAR.testnet.fetch_blocks do |block|
  puts [block.height, block.hash].join("\t")
end

Tracking chain transactions

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:

Tracking chain actions

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:

Tracking contract interactions

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:

Instantiating the CLI wrapper

# Use the NEAR testnet (the default):
testnet = NEAR::CLI.new(network: NEAR.testnet)

# Use the NEAR mainnet (to test in prod):
# mainnet = NEAR::CLI.new(network: NEAR.mainnet)

Viewing account details

# 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

# 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

# Create an account funded from a faucet (testnet only):
result = testnet.create_account_with_faucet(
  'mynewaccount.testnet',
  public_key: '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

# Delete an existing account:
result = testnet.delete_account(
  'my-obsolete-account.testnet',                # account to delete
  beneficiary: 'v2.faucet.nonofficial.testnet'  # account receiving remaining balance
)

Managing access keys

# 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

# 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

# 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

# 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

# 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

git clone https://github.com/dryruby/near.rb.git

---