btcruby 0.0.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 64bf9829ab2ad396b5a77eaf7a559b76ff2834cf
-  data.tar.gz: 9b08712780116753656e27884e32dd5ebee91823
+  metadata.gz: 259e4ee0ead1612a0af37185e4da5eef97238912
+  data.tar.gz: 1b7f28e68c728175a0fc2c499b57291e58b9df0d
 SHA512:
-  metadata.gz: 1e8b8c4617eb33b730bbaafef511a623852bd3a814def2eee5245ceb47c0c10e78b0d9080f969b218e0399a10ab4447e6b9b7b1e251e3d746fbdf07dc57faf66
-  data.tar.gz: 7c35a9ec7b63c5e2c8e6357f9bf0897c7481d6fab531b4080196501208ac6fa1ecd37f693f24aa79774778e40868cde1d6ce6e4604021aab305bf330efe7567d
+  metadata.gz: a0bb5fbceb5754b8a2ca60085aea0767adf9bec1b6fda5072dd11dd845f640b9aea7507900766165031f4d1b41851da48e0ef1dcb7fb4128311b81272eb5a232
+  data.tar.gz: a864ca92fe3cb78465c6bd4d1b9a042f0c9afbb495f7d7b6a77d224df6fd0b02234919fe6b887d4927d24db0dda7386a3f9f69c0a26ccd5234aeb4b0d3262178

data/.gitignore

@@ -0,0 +1,18 @@
+build/
+*.pbxuser
+!default.pbxuser
+*.mode1v3
+!default.mode1v3
+*.mode2v3
+!default.mode2v3
+*.perspectivev3
+!default.perspectivev3
+xcuserdata
+*.xccheckout
+*.moved-aside
+DerivedData
+*.hmap
+*.ipa
+*.xcuserstate
+*.xcodeproj
+*.xcodeproj/

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+- 2.1.1
+- 2.1.0
+notifications:
+  slack:
+    secure: ZbYOCxRusuhvSdSl6nW9/emtZTnwK+o1uuhMKK5yrWDVL/kNV/ejcGTuInOA8TW1ULv6fNI9j2c7Q+zSu3CDO5oTMM7PK4TNeKsCY4koyk+91QKltWIH+aAFpPzbMcWbvnTSzHzTkhRW3ZPhfcQTkb6MRLEA/B6SjmUVc5ADTtc=

data/FAQ.md

@@ -0,0 +1,7 @@
+
+BTCRuby FAQ
+===========
+
+This will answer questions like "what is compressed public key", "why when I convert private key to address it is not correct?" etc.
+
+

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+gemspec
+gem 'rake'

data/Gemfile.lock

@@ -0,0 +1,18 @@
+PATH
+  remote: .
+  specs:
+    btcruby (0.1.0)
+      ffi (~> 1.9, >= 1.9.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ffi (1.9.3)
+    rake (10.3.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  btcruby!
+  rake

data/HOWTO.md

@@ -0,0 +1,17 @@
+# BTCRuby HOWTO
+
+* [Generating Private/Public Keys](#generating-privatepublic-keys)
+
+## Generating Private/Public Keys
+
+```ruby
+require 'btcruby'
+require 'btcruby/extensions'
+
+key = BTC::Key.random
+
+prv = key.to_wif # => L2yVhzwp5F7NXUmP31j274MPjnWi7WbFs3qRJEcdrjyBZ9jmEdWb
+pub = key.address.to_s # => 15M8ocGxsWtaenLQy6hDKXeLHqQgG3ebpB
+
+puts [prv, pub].join(" - ")
+```

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2014 Chain Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

data/README.md

@@ -0,0 +1,59 @@
+# BTCRuby
+
+[![Build Status](https://magnum.travis-ci.com/oleganza/btcruby.svg?token=84LHn4zp2Z1676MxCHjR)](https://magnum.travis-ci.com/oleganza/btcruby)
+
+BTCRuby aims at clarity, security and flexibility. The API is designed simultenously
+with [CoreBitcoin](https://github.com/oleganza/CoreBitcoin) (Objective-C library) and polished on real-life applications.
+
+## Documentation and Examples
+
+Please see [BTCRuby Reference](documentation/index.md) for API documentation and examples.
+
+## Basic Features
+
+* Encoding/decoding of addresses, WIF private keys (`BTC::Address`).
+* APIs to construct and inspect blocks, transactions and scripts.
+* Native BIP32 and BIP44 ("HW Wallets") support (see `BTC::Keychain`).
+* Explicit APIs to handle compressed and uncompressed public keys.
+* Explicit APIs to handle mainnet/testnet (see `BTC::Network`)
+* Consistent API for data encoding used throughout the library itself (see `BTC::Data` and `BTC::WireFormat`).
+* Flexible transaction builder that can work with arbitrary data sources that provide unspent outputs.
+* Handy extensions on built-in classes (e.g. `String#to_hex`) are optional (see `extensions.rb`).
+* Optional attributes on Transaction, TransactionOutput and TransactionInput to hold additional data
+  provided by 3rd party APIs.
+
+## Advanced Features
+
+* ECDSA signatures are deterministic and normalized according to [RFC6979](https://tools.ietf.org/html/rfc6979) 
+  and [BIP62](https://github.com/bitcoin/bips/blob/master/bip-0062.mediawiki).
+* Automatic normalization of existing ECDSA signatures (see `BTC::Key#normalized_signature`).
+* Rich script analysis and compositing support (see `BTC::Script`).
+* Powerful diagnostics API covering the entire library (see `BTC::Diagnostics`).
+* Canonicality checks for transactions, public keys and script elements.
+* Fee computation and signature script simulation for building transactions without signing them.
+* Complete OpenAssets implementation: validating OpenAssets transactions, easy to use transaction builder, API for handling Asset Definition.
+
+## Philosophy
+
+* We use clear, expressive names for all methods and classes.
+* Self-contained implementation. Only external dependency is `ffi` gem that helps linking directly with OpenSSL.
+* For efficiency and consistency we use binary strings throughout the library (not the hex strings as in other libraries).
+* We do not pollute standard classes with our methods. To use utility extensions like `String#to_hex` you should explicitly `require 'btcruby/extensions'`.
+* We use OpenSSL `BIGNUM` implementation where compatibility is critical (instead of the built-in Ruby Bignum).
+* We enforces canonical and determinstic ECDSA signatures for maximum compatibility and security using native OpenSSL functions.
+* We treat endianness explicitly. Even though most systems are little-endian, it never hurts to show where indianness is important.
+
+The goal is to provide a complete Bitcoin toolkit in Ruby.
+
+## How to run tests
+
+```
+$ bundle install
+$ rake
+```
+
+## Authors
+
+* [Oleg Andreev](http://oleganza.com/)
+* [Ryan Smith](http://r.32k.io)
+

data/Rakefile

@@ -0,0 +1,6 @@
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.pattern = "spec/*_spec.rb"
+end
+
+task :default => :test

data/TODO.txt

@@ -0,0 +1,40 @@
+
+TODO:
+
+- verify integrity of the block after reading: hash all txs in a merkle root and compare with the declared merkle root.
+- add BIP70 payment request support
+- add convenience methods to handle BIP44 accounts in BTC::Keychain (like in CoreBitcoin)
+- add Bitcoin URI support to encode and parse `bitcoin:` URIs.
+
++ replace factory methods like `C.with_data` or `C.with_key` with initializer since we now throw exceptions instead of returning nil on input errors.
++ block and block header classes
++ redesigned transaction builder to return a result object like in CoreBitcoin
++ data helpers
++ tests
++ base58
++ addresses
++ simplify API for addresses: Address.address_with_string() -> Address.with_string()
++ add test for private key address
++ keys and signatures support
+  + canonical signature
+  + deterministic signatures: k = HMAC-SHA256(hash, privkey)
++ add ffi to Gemspec as a dependency
++ transaction parsing and composing
++ script parsing and composing
++ tx import/export in bitcoin-QT dictionary format
++ add docs for to_wif/from_wif
++ add diagnostics to check canonicality of the signature
++ BIP32 implementation: Keychain
++ base58/base58check mess: untangle
++ specs and fixes for zero-padded private keys
++ clearer testnet/mainnet API for Script
++ fee computation for transactions
++ signature_hash for transaction
++ transaction builder
++ tx ID conversion to/from hash
++ helper properties for Transaction and inputs/outputs to hold extra data received from APIs.
+
+- test tool to detect broken or non-canonical transactions
+
+- compact signatures support
+

data/bin/console

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+require_relative '../lib/btcruby.rb'
+require_relative '../lib/btcruby/extensions.rb'
+
+include BTC
+
+require 'irb'
+require 'irb/completion'
+
+# IRB.conf[:PROMPT]||={}
+# IRB.conf[:PROMPT][:BTC_PROMPT] = { # name of prompt mode
+#   :AUTO_INDENT => true,           # enables auto-indent mode
+#   :PROMPT_I => %{>>},             # normal prompt
+#   :PROMPT_S => %{">},             # prompt for continuated strings
+#   :PROMPT_C => %{*>},             # prompt for continuated statement
+#   :RETURN => "=>%s\n"             # format to return value
+# }
+# IRB.conf[:PROMPT_MODE] = :BTC_PROMPT
+IRB.start

data/btcruby.gemspec

@@ -0,0 +1,20 @@
+#encoding: UTF-8
+$:.push File.expand_path("../lib", __FILE__)
+require "btcruby/version"
+
+files = `git ls-files`.split("\n")
+
+Gem::Specification.new do |s|
+  s.name          = "btcruby"
+  s.email         = "oleganza+btcruby@gmail.com"
+  s.version       = BTC::VERSION
+  s.description   = "Ruby library for interacting with Bitcoin."
+  s.summary       = "Ruby library for interacting with Bitcoin."
+  s.authors       = ["Oleg Andreev", "Ryan Smith"]
+  s.homepage      = "https://github.com/oleganza/btcruby"
+  s.rubyforge_project = "btcruby"
+  s.license       = "MIT"
+  s.files         = files
+  s.require_paths = ["lib"]
+  s.add_runtime_dependency 'ffi', '~> 1.9', '>= 1.9.3'
+end

data/documentation/address.md

@@ -0,0 +1,73 @@
+[Index](index.md)
+
+BTC::Address
+============
+
+BTC::Address is a base class for [P2PKH](p2pkh.md), [P2SH](p2sh.md) addresses and [WIF](wif.md) private key serialization format. It is defined in **address.rb**.
+
+Use BTC::Address to *decode* addresses of the unknown type (or when it does not matter). Use subclasses to *encode* addresses of a specific type.
+
+Subclasses
+----------
+
+* [BTC::PublicKeyAddress](p2pkh.md)
+* [BTC::ScriptHashAddress](p2sh.md)
+* [BTC::WIF](wif.md)
+
+Class Methods
+-------------
+
+#### parse(*argument*)
+
+If `argument` is a String, parses it and returns an instance of one of the concrete subclasses of BTC::Address.
+
+If `argument` is a subclass of BTC::Address returns `argument`.
+
+```ruby
+>> Address.parse("1CBtcGivXmHQ8ZqdPgeMfcpQNJrqTrSAcG")
+=> #<BTC::PublicKeyAddress:1CBtcGiv...>
+
+>> Address.parse("3NukJ6fYZJ5Kk8bPjycAnruZkE5Q7UW7i8")
+=> #<BTC::ScriptHashAddress:3NukJ6fY...>
+
+>> Address.parse("5KQntKuhYWSRXNqp2yhdXzjekYAR7US3MT1715Mbv5CyUKV6hVe")
+=>  #<BTC::WIF:5KQntKuh... privkey:d20b62cd... (uncompressed pubkey)>
+```
+
+Instance Methods
+----------------
+
+#### data
+
+Returns an underlying binary string stored within an address.
+For [WIF](wif.md) format it is a 32-byte private key.
+For [P2PKH](p2pkh.md) or [P2PSH](p2sh.md) addresses it is a 20-byte hash.
+
+#### to_s
+
+Returns string representation of the address in [Base58Check](base58.md) encoding.
+
+#### network
+
+Returns a [BTC::Network](network.md) instance based on version prefix of the address (mainnet or testnet).
+
+#### version
+
+Returns an integer value of the one-byte prefix of the address.
+
+#### public_address
+
+Returns a corresponding public address. Typically returns `self`, but for [WIF](wif.md) returns
+an address based on the public key corresponding to the WIF-encoded private key.
+
+#### p2pkh?
+
+Returns `true` if this address is a subclass of [PublicKeyAddress](p2pkh.md). Otherwise returns `false`.
+
+#### p2sh?
+
+Returns `true` if this address is a subclass of [ScriptHashAddress](p2sh.md). Otherwise returns `false`.
+
+#### ==
+
+Returns `true` if underlying data and versions of both addresses match.

data/documentation/base58.md

@@ -0,0 +1,52 @@
+[Index](index.md)
+
+BTC::Base58
+===========
+
+**Base58** and **Base58Check** are two encodings invented by Satoshi for Bitcoin [addresses](addresses.md)
+to make sure they don't contain ambiguous characters and can be selected with a double click.
+
+Note: you normally do not use Base58 directly. To encode/decode Bitcoin addresses, use [BTC::Address](address.md) class.
+To encode/decode private keys in WIF format, use [BTC::WIF](wif.md) class.
+
+Satoshi:
+
+> Why base-58 instead of standard base-64 encoding?
+> - Don't want 0OIl characters that look the same in some fonts and could be used to create visually identical looking account numbers.
+> - A string with non-alphanumeric characters is not as easily accepted as an account number.
+> - E-mail usually won't line-break if there's no punctuation to break at.
+> - Double-clicking selects the whole number as one word if it's all alphanumeric.
+
+Base58 treats a binary string as a big-endian integer and encodes it in Base58 alphabet:
+
+```
+123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
+```
+
+Leading zero bytes are encoded as repeated "1"s.
+
+**Base58Check** appends a 4-byte portion of [Hash256](hash_functions.md) of the binary string as a checksum, then encodes the resulting string in Base58.
+
+Module Functions
+----------------
+
+#### base58\_from\_data(*data*)
+
+Returns a Base58-encoded string for a given binary string `data`.
+
+#### data\_from\_base58(*string*)
+
+Returns a binary string decoded from Base58-encoded `string`.
+
+Raises `FormatError` if encoding is not valid.
+
+#### base58check\_from\_data(*data*)
+
+Returns a Base58-encoded string with appended checksum for a given binary string `data`.
+
+#### data\_from\_base58check(*string*)
+
+Returns a binary string decoded from Base58Check-encoded `string`.
+
+Raises `FormatError` if checksum is not valid or encoding is not valid.
+

data/documentation/block.md

@@ -0,0 +1,127 @@
+[Index](index.md)
+
+BTC::Block
+==========
+
+BTC::Block represents a collection of transactions within the block chain.
+It consists of [block header](block_header.md) and an array of [transactions](transaction.md).
+
+Class Methods
+-------------
+
+#### genesis_mainnet
+
+Returns a genesis block for [mainnet](network.md#mainnet). See also [BTC::Network#genesis_block](network.md#genesis_block).
+
+#### genesis_testnet
+
+Returns a genesis block for [testnet](network.md#testnet). See also [BTC::Network#genesis_block](network.md#genesis_block).
+
+Initializers
+------------
+
+#### new(data: *String*)
+
+Returns a new block initialized with a binary string in [wire format](wire_format.md).
+Raises `ArgumentError` if block is incomplete or incorrectly encoded.
+
+#### new(stream: *IO*)
+
+Returns a new block initialized with data in [wire format](wire_format.md) read from a given stream.
+Raises `ArgumentError` if block is incomplete or incorrectly encoded.
+
+#### new(*attributes*)
+
+Returns a new block with named [attributes](#attributes). All attributes are optional and have appropriate default values.
+
+```ruby
+Block.new(
+  version: 2,
+  previous_block_id: "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f",
+  merkle_root: "...",
+  transactions: [...])
+```
+
+Attributes
+----------
+
+#### version
+
+Block version (1 or 2).
+
+#### previous\_block\_hash
+
+Binary hash of the previous block.
+
+#### previous\_block\_id
+
+Hex big-endian hash of the previous block. See [Hash↔ID Conversion](hash_id.md).
+
+#### merkle_root
+
+Binary root hash of the transactions’ merkle tree.
+
+#### timestamp
+
+32-bit unsigned UNIX timestamp.
+
+#### time
+
+Time object derived from timestamp
+
+#### bits
+
+Proof-of-work target in a compact form (uint32). See [Proof-of-Work Conversion Routines](proof_of_work.md).
+
+#### nonce
+
+Proof-of-work nonce (uint32 value iterated during mining).
+
+#### transactions
+
+List of [BTC::Transaction](transaction.md) instances contained within the block.
+
+#### height
+
+Optional height in the block chain (genesis block has height 0).
+Not stored within block's [binary representation](#data).
+Third party APIs may set this value for user’s convenience.
+
+#### confirmations
+
+Optional number of the confirmations for transactions in this block.
+If this block is the latest one, `confirmations` equals 1.
+Not stored within block's [binary representation](#data).
+Third party APIs may set this value for user’s convenience.
+
+
+Instance Methods
+----------------
+
+#### block_hash
+
+Binary hash of the block. Equals `SHA256(SHA256(header_data))`.
+
+#### block_id
+
+Hex big-endian hash of the block. See [Hash↔ID Conversion](hash_id.md).
+
+#### block_header
+
+Returns a [BTC::BlockHeader](block_header.md) instance containing all attributes of this block except `transactions`.
+
+#### header_data
+
+Returns block’s header data in [wire format](wire_format.md).
+
+#### data
+
+Returns block’s entire data in [wire format](wire_format.md).
+
+#### dup
+
+Returns a copy of the block.
+
+#### ==
+
+Returns `true` if binary representation of both blocks is equal (external attributes `height`, `confirmations` are ignored).

data/documentation/block_header.md

@@ -0,0 +1,120 @@
+[Index](index.md)
+
+BTC::BlockHeader
+================
+
+Block header is a part of the [block](block.md) that contains date, merkle root of the block's [transactions](transaction.md) and additional data related to proof-of-work.
+
+Class Methods
+-------------
+
+#### genesis_mainnet
+
+Returns a genesis block header for [mainnet](network.md#mainnet).
+See also [BTC::Network#genesis_block_header](network.md#genesis_block_header).
+
+#### genesis_testnet
+
+Returns a genesis block header for [testnet](network.md#testnet).
+See also [BTC::Network#genesis_block_header](network.md#genesis_block_header).
+
+Initializers
+------------
+
+#### new(data: *String*)
+
+Returns a new block header initialized with a binary string in [wire format](wire_format.md).
+Raises `ArgumentError` if block header is incomplete or incorrectly encoded.
+
+#### new(stream: *IO*)
+
+Returns a new block header initialized with data in [wire format](wire_format.md) read from a given stream.
+Raises `ArgumentError` if block header is incomplete or incorrectly encoded.
+
+#### new(*attributes*)
+
+Returns a new block header with named [attributes](#attributes). All attributes are optional and have appropriate default values.
+
+```ruby
+BlockHeader.new(
+  version: 2,
+  previous_block_id: "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f",
+  merkle_root: "...",
+  timestamp: ...)
+```
+
+Attributes
+----------
+
+#### version
+
+Block version (1 or 2).
+
+#### previous\_block\_hash
+
+Binary hash of the previous block.
+
+#### previous\_block\_id
+
+Hex big-endian hash of the previous block. See [Hash↔ID Conversion](hash_id.md).
+
+#### merkle_root
+
+Binary root hash of the transactions’ merkle tree.
+
+#### timestamp
+
+32-bit unsigned UNIX timestamp.
+
+#### time
+
+Time object derived from timestamp
+
+#### bits
+
+Proof-of-work target in a compact form (uint32). See [Proof-of-Work Conversion Routines](proof_of_work.md).
+
+#### nonce
+
+Proof-of-work nonce (uint32 value iterated during mining).
+
+#### height
+
+Optional height in the block chain (genesis block has height 0).
+Not stored within block's [binary representation](#data).
+Third party APIs may set this value for user’s convenience.
+
+#### confirmations
+
+Optional number of the confirmations for transactions in this block.
+If this block is the latest one, `confirmations` equals 1.
+Not stored within block's [binary representation](#data).
+Third party APIs may set this value for user’s convenience.
+
+
+Instance Methods
+----------------
+
+#### block_hash
+
+Binary hash of the block header. Equals `SHA256(SHA256(header_data))`.
+
+#### block_id
+
+Hex big-endian hash of the block header. See [Hash↔ID Conversion](hash_id.md).
+
+#### header_data
+
+Returns block’s header data in [wire format](wire_format.md).
+
+#### data
+
+Returns `header_data`.
+
+#### dup
+
+Returns a copy of the block header.
+
+#### ==
+
+Returns `true` if binary representation of both block headers is equal (external attributes `height`, `confirmations` are ignored).