**This version works and was on its way to be an engine for rails but I have since redesigned the entire project and rewrote it as a service with its own API to make it much more flexible. This version is not ready to release open source yet but I will make another branch and push the changes soon.**
Ruby-Wallet¶ ↑
Ruby-Wallet provides abstracted access to any Bitcoin based coind JSON-RPC API. Ruby-Wallet organizes all the necessary features within a secure wallet abstraction, and utilizes its own double-entry bookkeeping account management system built using MongoDB.
The built-in coind account management system has many flaws (balances are calculated by iterating through every transaction in the wallet, causing it to be slower as the number of transactions grow) and will be removed in later versions of Bitcoin (github.com/bitcoin/bitcoin/issues/3816). Utilizing MongoDB to handle internal account transactions and balance management allows for live backups via replication to offsite MongoDB instances, fast/robust queries for wallet information and keeps the wallet.dat file small and minimal.
Installation¶ ↑
Clone the repository, copy the sample config files to make config files. Compile the gem and install it locally, or specify the folder in your Gemfile.
clone https://github.com/ruby-wallet/ruby-wallet
Copy and configure the gem database, encryption key for passwords, and coin(s) to manage to your setup
cd ruby-wallet/config cp mongoid.sample.yml mongoid.yml cp config.sample.yml config.yml cp coins.sample.yml coins.yml
Modify the env.rb file to match your environment.
Compile the gem and install it locally
gem build ruby-wallet.gemspec gem install ruby-wallet
Alternatively you can specify the local folder, as in your vendor folder in Rails, in your Gemfile
gem 'ruby-wallet', path: 'vendor/ruby-wallet'
Usage¶ ↑
The simplest possible usage after configuration is complete
RubyWallet.connect("BTC").unconfirmed_balance # => 0.001 RubyWallet.connect("BTC").confirmed_balance # => 0.001
Confirm if addresses are valid using the wallet method
wallet.valid_address?(address) # => true
Confirm address is owned by current wallet
wallet.own_address?(address) # => true
A wallet has transactions, transfers and accounts embedded inside.
wallet.transactions wallet.transfers wallet.accounts
Sync the abstracted wallet transactions with the coind client. The sync method is designed to be called from blocknotify.
wallet.sync
Sync a specific transaction with the coind client. The transaction sync method is designed to be called from walletnotify.
wallet.sync_transaction(transaction_id)
The configuration file provides the fixed transaction fee for withdrawals and the confirmations required for a transaction to be confirmed.
wallet.transaction_fee wallet.confirmations
From the wallet you can create accounts and generate addresses to be associated with a specified account.
wallet.create_account(label) wallet.generate_address(label)
A transfer is handled indepedent of the coind client and only exists within the MongoDB account management abstraction. When a transfer is preformed two separate transfers are created, a “send” which removes money from the sender account and “receive” which adds money to the recipient account.
wallet.transfer(sender, recipient, amount, comment)
A withdrawal is only possible from an account and checks against available balance.
wallet.withdrawal(sender, address, amount)
Wallet Encryption¶ ↑
Encrypting your wallet with the password supplied in the config file will enable encryption. The encryption password is stored encrypted in the database, and before every action, an unlock command will be used to unlock and automatically relock your wallet between protected actions. If your wallet is encrypted prior to setup, you must manually set the encrypted attribute to true.
wallet.encrypt wallet.encrypted? # => true
Wallet Accounts¶ ↑
A wallet embeds many accounts, each account organizes one or more coind addresses by label. Account management is handled by ruby-wallet using a MongoDB database abstracted above the coind client.
account = wallet.create_account(label) account.label # returns label used within the wallet.dat file to associate addresses account.addresses # returns an array of addresses associated with the account, new addresses are last account.total_received # returns the total amount received by the account account.balance(minimum_confirmations) # returns the balance of the account account.transactions # returns associated deposits and withdrawals account.deposits # returns associated deposits account.withdrawals # returns associated withdrawals account.transfers # returns associated transfers
Withdraw coins from an account, with validations to prevent overspending.
account.withdraw(address, 5,5) # sends 5.5 coins to the withdrawal address
Transfer coins from one account to another, with validations to prevent overspending. Transfers do not create “move” transactions in the wallet.dat.
account.transfer(recipeint_label, 5.5) # sends 5.5 coins to the recipient account
Account Transactions¶ ↑
A transaction exists on the blockchain, are aggregated from the coind client and can be either a deposit or withdrawal.
transaction.transaction_id # returns txid from coind transaction.account # returns account MongoDB object transaction.account_label transaction.account_id # returns internal account MongoDB _id transaction.category # returns either "send" or "receive" transaction.address transaction.amount transaction.confirmations transaction.occurred_at transaction.received_at transaction.timestamp
The number of confirmations to be considered confirmed is specified in the coins.yml config. For greater efficency, once confirmed transaction confirmations are no longer updated.
transaction.confrim # sets the confirmed Boolean to true if confirmations >= wallet.confirmations transaction.confirmed? # => true
Account Transfers¶ ↑
A transfer exists only within MongoDB account management abstraction in ruby-wallet. Each transfer creates two objects, for double-entry bookkeeping, that track coin movement between accounts.
transfer.sender # returns account MongoDB object transfer.sender_id # returns internal account MongoDB _id transfer.recipient # returns account MongoDB object transfer.recipient_id # returns internal account MongoDB _id transaction.category # returns "send" or "receive" transaction.amount transaction.comment transfer.timestmap
Future Plans¶ ↑
Implement easy way to utilize multi-signatures, automatically prune slow nodes from connection list, use the raw transaction API to increase efficency.
Build out a sinatra API for the higher levels of the stack to communicate with. This would allow this abstraction to be more flexible in stack placement. Currently you can switch out coind for something like btcd, it would be nice to be able to easily use something other than a ruby program higher in the stack.
Donate to the ruby-wallet project:
BTC 1LJtuko15Ck1gq5H9K24iGnA1yvtcBMYa4
BLK BQJMnqMBY3qRzu9HQFvXC4UVprtPjMvsZM
License¶ ↑
RubyWallet - Ruby Coind Wallet Abstraction Copyright © 2014 Blackwave Labs
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <www.gnu.org/licenses/>.