= Bitcoin-ruby {}[http://travis-ci.org/lian/bitcoin-ruby] {
}[http://inch-ci.org/github/lian/bitcoin-ruby] {
}[https://tip4commit.com/github/lian/bitcoin-ruby]
This is a ruby library for interacting with the bitcoin protocol/network.
Some of the main features are:
== Compatible with...
== Installation
gem install bitcoin-ruby
git clone https://github.com/lian/bitcoin-ruby.git; cd bitcoin-ruby; bundle install
Note that some aspects of the library (such as networking, storage, etc.) need additional dependencies which are not specified in the gemspec. The core requirements are intentionally kept to a minimum, so nobody has to install unneeded dependencies.
If you would like to install using Bundler, put it in your Gemfile and run bundle install gem 'bitcoin-ruby', git: 'https://github.com/lian/bitcoin-ruby', branch: 'master', require: 'bitcoin'
== Library Usage
There are different aspects to the library which can be used separately or in combination. Here are some ideas of what you could do. There are also some demo scripts in examples/, see EXAMPLES.
=== Keys/Addresses
Generate a Bitcoin::Key
key = Bitcoin::Key.generate key.priv key.pub key.addr sig = key.sign("data") key.verify("data", sig) recovered_key = Bitcoin::Key.from_base58(key.to_base58)
=== Blocks / Transactions parsing
Parse a Bitcoin::Protocol::Block
raw_block = File.open('spec/bitcoin/fixtures/rawblock-0.bin', 'rb') {|f| f.read} blk = Bitcoin::Protocol::Block.new(raw_block) blk.hash #=> 00000000839a8e6886ab5951d76f411475428afc90947ee320161bbf18eb6048 blk.tx.count #=> 1 blk.to_hash #=> ... Bitcoin::Protocol::Block.from_json( blk.to_json )
Parse a Bitcoin::Protocol::Tx
raw_tx = File.open('spec/bitcoin/fixtures/rawtx-01.bin', 'rb') {|f| f.read} tx = Bitcoin::Protocol::Tx.new(raw_tx) tx.hash #=> 6e9dd16625b62cfcd4bf02edb89ca1f5a8c30c4b1601507090fb28e59f2d02b4 tx.in.size #=> 1 tx.out.size #=> 2 tx.to_hash #=> ... Bitcoin::Protocol::Tx.from_json( tx.to_json )
Bitcoin::Script.new(tx.out[0].pk_script).to_string
=== Transaction verification / Scripts
Get the matching transactions (in this example tx1 is the spending transaction)
rawtx1 = File.open("spec/bitcoin/fixtures/rawtx-f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16.bin", 'rb') {|f| f.read} rawtx2 = File.open("spec/bitcoin/fixtures/rawtx-0437cd7f8525ceed2324359c2d0ba26006d92d856a9c20fa0241106ee5a597c9.bin", 'rb') {|f| f.read} tx1 = Bitcoin::Protocol::Tx.new(rawtx1) tx2 = Bitcoin::Protocol::Tx.new(rawtx2)
Then simply ask the transaction to verify an input
tx1.verify_input_signature(0, tx2) #=> true
=== Scripts
If you want to control the Bitcoin::Script yourself, you can do so
txin = tx1.in.first txout = tx2.out[txin.prev_out_index] script = Bitcoin::Script.new(txin.script_sig + txout.pk_script)
result = script.run do |pubkey, sig, hash_type| hash = tx1.signature_hash_for_input(0, nil, txout.pk_script) Bitcoin.verify_signature(hash, sig, pubkey.unpack("H*")[0]) end result #=> true
=== Create Transactions
You need to know the previous output you want to spend (tx hash and output index), as well as the private key for the address required to sign for it.
Bitcoin.network = :testnet3
include Bitcoin::Builder
prev_hash = "6c44b284c20fa22bd69c57a9dbff91fb71deddc8c54fb2f5aa41fc78c96c1ad1"
prev_out_index = 0
prev_tx = Bitcoin::P::Tx.from_json(open("http://test.webbtc.com/tx/#{prev_hash}.json"))
key = Bitcoin::Key.from_base58("92ZRu28m2GHSKaaF2W7RswJ2iJYpTzVhBaN6ZLs7TENCs4b7ML8")
new_tx = build_tx do |t|
t.input do |i| i.prev_out prev_tx i.prev_out_index prev_out_index i.signature_key key end
t.output do |o| o.value 50000000 # 0.5 BTC in satoshis o.script {|s| s.recipient "mugwYJ1sKyr8EDDgXtoh8sdDQuNWKYNf88" } end
t.output do |o| o.value 49000000 # 0.49 BTC, leave 0.01 BTC as fee o.script {|s| s.recipient key.addr } end
end
puts new_tx.to_json
== Documentation
Always trying to improve, any help appreciated! If anything is unclear to you, let us know!
Documentation is generated using yardoc:
rake doc
The specs are also a good place to see how something works.
== Specs
Specs require libsecp256k1 in order to be fully run. Therefore, the first step in running the specs is to build this library if you haven't already:
rake build_libsecp256k1
The majority of specs can be run with
rake rspec
or, if you want to run a single spec
bundle exec rspec spec/bitcoin/bitcoin_spec.rb
If you make changes to the code or add functionality, please also add specs.
To run specs for changes that monkey patch significant functionality, you should run the specs individually. For example, to run the Dogecoin specs:
rake coin_spec[dogecoin]
If support is added for any new coins a corresponding coin spec should also be added to test specific functionality of that coin.
== Development
Any help or feedback is greatly appreciated! From getting knee-deep into elliptic-curve acrobatics, to cleaning up high-level naming conventions, there is something for everyone to do. Even if you are completely lost, just pointing out what is unclear helps a lot!
If you are curious or like to participate in development, drop by #bitcoin-ruby on irc.freenode.net!
== License
Available here: [link:COPYING]