btcruby 0.0.0 → 1.0.0

data/documentation/p2pkh.md

@@ -0,0 +1,71 @@
+[Index](index.md)
+
+BTC::PublicKeyAddress
+=====================
+
+A subclass of [BTC::Address](address.md) that represents an address based on the public key (pay-to-public-key-hash, P2PKH).
+
+Initializers
+------------
+
+#### new(string: *String*)
+
+Returns a new address by parsing a [Base58Check](base58.md)-encoded string that must represent a valid P2PKH address.
+
+#### new(hash: *String*, network: *BTC::Network*)
+
+Returns a new address with a 20-byte binary string `hash`.
+
+If `network` is not specified, [BTC::Network.default](network.md#default) is used.
+
+#### new(public_key: *String*, network: *BTC::Network*)
+
+Returns a new address with a hash of the binary string `public_key`.
+
+If `network` is not specified, [BTC::Network.default](network.md#default) is used.
+
+#### new(key: *BTC::Key*, network: *BTC::Network*)
+
+Returns a new address with a hash of the `key.public_key`.
+
+If `network` is not specified, `key.network` is used.
+
+
+Instance Methods
+----------------
+
+#### hash
+
+Returns a 20-byte binary hash stored within the address.
+
+#### to_s
+
+Returns string representation of the address in [Base58Check](base58.md) encoding.
+
+#### network
+
+Returns a [BTC::Network](network.md) instance based on the version prefix of the address (mainnet or testnet).
+
+#### version
+
+Returns an integer value of the one-byte prefix of the address. 0 for mainnet, 111 for testnet.
+
+#### public_address
+
+Returns `self`.
+
+#### p2pkh?
+
+Returns `true`.
+
+#### p2sh?
+
+Returns `false`.
+
+#### script
+
+Returns [BTC::Script](script.md) instance that can be used in the [transaction output](transaction_output.md) to send bitcoins to this address.
+
+
+
+

data/documentation/p2sh.md

@@ -0,0 +1,64 @@
+[Index](index.md)
+
+BTC::ScriptHashAddress
+=====================
+
+A subclass of [BTC::Address](address.md) that represents an address based on the redeem [script](script.md) (pay-to-script-hash, P2SH).
+
+Initializers
+------------
+
+#### new(string: *String*)
+
+Returns a new address by parsing a [Base58Check](base58.md)-encoded string that must represent a valid P2SH address.
+
+#### new(hash: *String*, network: *BTC::Network*)
+
+Returns a new address with a 20-byte binary `hash`.
+
+If `network` is not specified, [BTC::Network.default](network.md#default) is used.
+
+#### new(redeem_script: *BTC::Script*, network: *BTC::Network*)
+
+Returns a new address with a hash of the [BTC::Script](script.md) (so-called “redeem script”).
+
+If `network` is not specified, [BTC::Network.default](network.md#default) is used.
+
+
+Instance Methods
+----------------
+
+#### hash
+
+Returns a 20-byte binary hash stored within the address.
+
+#### to_s
+
+Returns string representation of the address in [Base58Check](base58.md) encoding.
+
+#### network
+
+Returns a [BTC::Network](network.md) instance based on the version prefix of the address (mainnet or testnet).
+
+#### version
+
+Returns an integer value of the one-byte prefix of the address. 5 for mainnet, 196 for testnet.
+
+#### public_address
+
+Returns `self`.
+
+#### p2pkh?
+
+Returns `false`.
+
+#### p2sh?
+
+Returns `true`.
+
+#### script
+
+Returns [BTC::Script](script.md) instance that can be used in the [transaction output](transaction_output.md) to send bitcoins to this address. 
+
+Note: do not confuse this with the “redeem script” that is compressed within the address's *hash*. 
+

data/documentation/proof_of_work.md

@@ -0,0 +1,84 @@
+[Index](index.md)
+
+BTC::ProofOfWork
+================
+
+ProofOfWork module defines functions to convert between different kinds of difficulty and proof of work representations.
+
+* **Target** is big unsigned integer derived from 256-bit hash (interpreted as little-endian integer).
+Hash of a valid block should be below target.
+* **Bits** is a "compact" representation of a target as uint32.
+* **difficulty** is a floating point multiple of the minimum difficulty.
+Difficulty = 2 means the block is 2x more difficult than the minimal difficulty.
+
+You can use all functions as methods on `ProofOfWork` object.
+
+Constants
+---------
+
+#### MAX\_TARGET\_MAINNET
+
+Defines the minimum difficulty for the proof of work on mainnet blockchain. See also [Network#max_target](network.md#max_target).
+
+Equals `0x00000000ffff0000000000000000000000000000000000000000000000000000`.
+
+#### MAX\_TARGET\_TESTNET
+
+Defines the minimum difficulty for the proof of work on testnet blockchain. See also [Network#max_target](network.md#max_target).
+
+Equals `0x00000007fff80000000000000000000000000000000000000000000000000000`.
+
+
+Module Functions
+----------------
+
+#### bits\_from\_target(*target*)
+
+Converts a 256-bit integer (*Bignum*) to 32-bit compact representation (*Fixnum*).
+
+```ruby
+>> ProofOfWork.bits_from_target(0x00000000ffff0000000000000000000000000000000000000000000000000000)
+=> 0x1d00ffff
+```
+
+#### target\_from\_bits(*bits*)
+
+Converts a 32-bit compact representation of the target to a 256-bit integer (*Bignum*).
+
+```ruby
+>> ProofOfWork.target_from_bits(0x1d00ffff)
+=> 0x00000000ffff0000000000000000000000000000000000000000000000000000
+```
+
+#### bits\_from\_difficulty(*difficulty*, max\_target: MAX\_TARGET\_MAINNET)
+
+Computes bits from difficulty. Could be inaccurate since difficulty is a limited-precision floating-point number.
+
+If not specified, `max_target` equals `MAX_TARGET_MAINNET`.
+
+#### difficulty\_from\_bits(*bits*, max\_target: MAX\_TARGET\_MAINNET)
+
+Computes difficulty from bits.
+
+If not specified, `max_target` equals `MAX_TARGET_MAINNET`.
+
+#### target\_from\_difficulty(*difficulty*, max\_target: MAX\_TARGET\_MAINNET)
+
+Computes target from difficulty. Could be inaccurate since difficulty is a limited-precision floating-point number.
+
+If not specified, `max_target` equals `MAX_TARGET_MAINNET`.
+
+#### difficulty\_from\_target(*target*, max\_target: MAX\_TARGET\_MAINNET)
+
+Compute relative difficulty from a given target.
+E.g. returns 2.5 if target is 2.5 times harder to reach than the `max_target`.
+
+If not specified, `max_target` equals `MAX_TARGET_MAINNET`.
+
+#### hash\_from\_target(*target*)
+
+Converts target integer to a binary little-endian 32-byte string padded with zero bytes.
+
+#### target\_from\_hash(*hash*)
+
+Converts 32-byte binary string to a target integer (`hash` is treated as a little-endian integer).

data/documentation/script.md

@@ -0,0 +1,280 @@
+[Index](index.md)
+
+BTC::Script
+===========
+
+Script is a string of [opcodes](opcode.md) specifying conditions that allow moving bitcoins from one transaction to another.
+
+Script can be used in two contexts:
+
+* In [transaction outputs](transaction_output.md), as a predicate (e.g. “only an owner of this key is allowed to spend funds”).
+Such script is called simply a **script** or a **scriptPubKey**.
+* In [transaction inputs](transaction_input.md), as an input to a script from a corresponding output
+(e.g. “here is a signature made with the key mentioned in the output”).
+Such script is called a **signature script** or a **scriptSig**.
+
+Typically an output script contains interesting opcodes while the input script contains only static data, without any opcodes
+(because any operations in the input script can be always pre-computed).
+
+In case of [P2SH](p2sh.md) payments, the output script contains only a hash of an actual predicate script.
+The input script then contains both the static data and a corresponding predicate script (called "redemption script").
+
+
+Initializers
+------------
+
+#### new()
+
+Returns a new empty `BTC::Script` instance. Use `<<` or `+` operators to add operators to the script.
+
+```ruby
+>> Script.new << OP_9 << "some pushdata operation" << OP_VERIFY
+=> OP_9 736f6d65207075736864617461206f7065726174696f6e OP_VERIFY
+```
+
+#### new(hex: *String*)
+
+Returns a new `BTC::Script` instance deserialized from a given hex-encoded string.
+
+```ruby
+>> Script.new(hex: "76a914f2b27f7f9e519a6e77228a603c5c9a8434946a2288ac")
+=> OP_DUP OP_HASH160 f2b27f7f9e519a6e77228a603c5c9a8434946a22 OP_EQUALVERIFY OP_CHECKSIG
+```
+
+#### new(data: *String*)
+
+Returns a new `BTC::Script` instance deserialized from a given binary string.
+
+```ruby
+>> Script.new(data: "76a914f2b27f7f9e519a6e77228a603c5c9a8434946a2288ac".from_hex)
+=> OP_DUP OP_HASH160 f2b27f7f9e519a6e77228a603c5c9a8434946a22 OP_EQUALVERIFY OP_CHECKSIG
+```
+
+#### new(op\_return: *String* or *Array of Strings*)
+
+Returns a new `BTC::Script` instance containing `OP_RETURN` opcode followed by one or more *pushdata* binary strings.
+
+```ruby
+>> Script.new(op_return: "correct horse battery staple")
+=> OP_RETURN 636f727265637420686f727365206261747465727920737461706c65
+
+>> Script.new(op_return: ["correct horse battery", "battery staple correct"])
+=> OP_RETURN 636f727265... 6261747465...
+```
+
+#### new(public\_keys: *Array*, signatures\_required: *Integer*)
+
+Returns a new `BTC::Script` instance containing an `OP_CHECKMULTISIG` opcode with the provided public keys and a required number of signatures:
+
+```ruby
+>> a, b, c = [1,2,3].map{ Key.random.public_key }
+>> Script.new(public_keys: [a, b, c], signatures_required: 2)
+=> OP_2 0357f93e... 025f3ed5... 021a90c5... OP_3 OP_CHECKMULTISIG
+```
+
+
+Instance Methods
+----------------
+
+#### data
+
+Returns a serialized binary form of the script.
+
+#### standard?
+
+Returns `true` if this script is of standard kind. Valid non-standard scripts are allowed,
+but are not relayed by nodes with default configuration and may take longer to be included in a block.
+
+As of March 2015, scripts returning `true` from the following methods are considered standard:
+
+* `public_key_hash_script?`
+* `script_hash_script?`
+* `standard_multisig_script?`
+* `public_key_script?`
+* `standard_op_return_script?`
+
+#### data_only?
+
+Returns `true` if the script consists of *pushdata* operations only (uncluding small integer opcodes: `OP_0`, `OP_1` etc).
+This is used to verify input script for [P2SH](p2sh.md) output.
+
+#### to_s
+
+Returns a human-readable representation of script. E.g. instead of raw binary `76a914f2b2...` returns `"OP_DUP OP_HASH160 f2b2..."`.
+
+#### to_a
+
+Returns an array of [opcodes](opcode.md) (integers) and *pushdatas* (strings). `OP_0` is encoded as an empty string.
+
+#### to_hex
+
+Returns a raw binary representation of script (see `data`) in hex encoding.
+
+#### dup
+
+Returns a complete copy of a script.
+
+#### ==
+
+Returns true if both scripts can be serialized in the same binary string.
+
+
+
+### Regular Scripts
+
+
+#### public\_key\_script?
+
+Returns `true` if the script is of form `<pubkey> OP_CHECKSIG` (rarely used pay-to-pubkey script).
+  
+#### public_key
+
+Returns a raw public key if this script is `public_key_script?`.
+  
+#### public\_key\_hash\_script?
+
+Returns `true` if this script is a [P2PKH](p2pkh.md) script (`OP_DUP OP_HASH160 <20-byte hash> OP_EQUALVERIFY OP_CHECKSIG`).
+This is the most used kind of script that corresponds to a [pay-to-pubkey-hash](p2pkh.md) address.
+
+#### public\_key\_hash
+
+Returns a 20-byte hash of the public key if this script is `public_key_hash_script?`.
+
+#### script\_hash\_script?
+
+Returns `true` if this script is a [P2SH](p2sh.md) script (`OP_HASH160 <20-byte hash> OP_EQUAL`).
+
+#### script_hash
+
+Returns a 20-byte hash of the script if this script is `script_hash_script?`.
+
+
+
+### Null Data (OP_RETURN) Scripts
+
+#### op\_return\_script?
+
+Returns `true` if this script contains `OP_RETURN` opcode followed by pushdata.
+
+#### standard\_op\_return\_script?
+
+Returns `true` if this script contains `OP_RETURN` opcode followed by one pushdata string with a length of 40 bytes or less.
+
+#### op\_return\_data
+
+Returns the first *pushdata* string if this script is `op_return_script?`.
+
+#### op\_return\_items
+
+Returns all *pushdata* strings if this script is `op_return_script?`.
+
+
+
+
+### Multisig Scripts
+
+#### multisig\_script?
+
+Returns `true` if this script is a valid multisig script of form `<M> <public keys> <N> OP_CHECKMULTISIG` where:
+  
+* Both N and M are greater than zero
+* N is greater or equal M
+* N equals the number of public keys.
+
+Both *N* and *M* can be encoded as small integer [opcodes](opcode.md) (`OP_1` to `OP_16`) or as *pushdatas* containing little-endian integers.
+
+#### standard\_multisig\_script?
+
+Returns `true` if this script is a multisig script with additional constraints:
+
+* Both *N* and *M* are encoded as small integer opcodes (`OP_1`, `OP_2` etc.)
+* Both *N* and *M* are not greater than 15.
+
+Note: this applies to multisig scripts used as *redeem scripts* within [P2SH](p2sh.md).
+Standard bare multisig scripts (not wrapped in P2SH) must have *N* no greater than 3.
+
+#### multisig\_public\_keys
+
+Returns an array of raw public keys if this script is `multisig_script?`.
+
+#### multisig\_signatures\_required
+
+Returns a number of required signatures if this script is `multisig_script?`.
+
+
+
+### Conversion
+
+#### standard_address(network: *BTC::Network*)
+
+Returns [BTC::PublicKeyAddress](p2pkh.md) or [BTC::ScriptHashAddress](p2sh.md) if
+the script is a standard output script for these addresses.
+Returns `nil` for all other scripts.
+
+If `network` is not specified, [BTC::Network.default](network.md#default) is used.
+
+#### p2sh_script
+
+Returns a [P2SH](p2sh.md) script that wraps the receiver: `OP_HASH160 #{script.data.hash160} OP_EQUAL`.
+
+#### simulated\_signature\_script(strict: true|false)
+
+Returns a dummy *signature script* of the same length and structure as the intended *signature script* for the receiver. 
+Only a few standard script types are supported.
+
+Set `strict` to `false` to allow imprecise guess for P2SH script (2-of-3 multisig). Default is `true`.
+
+Returns `nil` if could not determine a matching script.
+
+
+
+
+### Modification
+
+
+#### append_opcode(opcode)
+
+Appends a non-pushdata opcode to the script.
+
+#### append_pushdata(string, opcode: *Integer*)
+
+Appends a pushdata opcode with binary `string` in the most compact encoding.
+
+Optional `opcode` may be equal to `OP_PUSHDATA1`, `OP_PUSHDATA2`, or `OP_PUSHDATA4` to specify a non-compact encoding.
+
+Raises `ArgumentError` if opcode does not represent a given string length.
+
+#### delete_opcode(opcode)
+
+Removes all occurences of the `opcode`. Typically used by verification engine to remove `OP_CODESEPARATOR`.
+
+#### delete_pushdata(string)
+
+Removes all occurences of *pushdata* opcodes containing `string`.
+
+#### append_script(script)
+
+Appends a `BTC::Script` instance to receiver.
+
+#### <<(*script*)
+
+Appends `BTC::Script` instance to receiver. Same as `append_script(script)`.
+
+#### <<(*Integer*)
+
+Appends an opcode specified by the *Integer*. Same as `append_opcode(integer)`.
+
+#### <<(*String*)
+
+Appends a *pushdata* opcode with a given string. Same as `append_pushdata(string)`.
+
+#### <<(*Array*)
+
+Appends an array of `BTC::Script` instances, opcode and strings. Array may contain nested arrays.
+
+#### +
+
+Returns a copy of the receiver with appended object using `<<`. It is defined as `self.dup << argument`.
+
+
+

data/documentation/signature.md

@@ -0,0 +1,71 @@
+[Index](index.md)
+
+Bitcoin Signatures
+==================
+
+Bitcoin uses ECDSA signatures that prove that an owner of a certain [private key](key.md#private_key) 
+acknowledges a certain message (usually a [transaction](transaction.md)).
+
+One or more signatures are used in a [transaction input](transaction_input.md) to prove that
+the owner of bitcoins locked in a corresponding [output](transaction_output.md) allows spending them in this specific transaction.
+
+Within Bitcoin transactions, signature contains an extra byte (*hash type*) that specifies how exactly the transaction must be transformed before being signed.
+To differentiate between regular signatures and signatures with a hash type, we use the following terms:
+
+**Signature** is a DER-encoded ECDSA signature.
+
+**Script Signature** is a DER-encoded ECDSA signature with an appended *hashtype* byte.
+
+Hash Types
+----------
+
+Hash type determines how [OP_CHECKSIG](opcode.md#op_checksig) hashes the [transaction](transaction.md)
+to verify the signature in a [transaction input](transaction_output.md).
+Depending on hash type, transaction is modified in some way before its hash is computed.
+Hash type is 1 byte appended to a signature in a [transaction input](transaction_input.md).
+
+First three types are mutually exclusive (tested using `hashtype & 0x1F`).
+`SIGHASH_ANYONECANPAY` type can be combined together with any of the first three types.
+
+#### BTC::SIGHASH_ALL = 0x01
+
+Default. Signs all inputs and outputs.
+Other inputs have scripts and sequences zeroed out, current input has its script
+replaced by the previous transaction's output script (or, in case of [P2SH](p2sh.md),
+by the signatures and the redemption script).
+
+If `(hashtype & SIGHASH_OUTPUT_MASK)` is not `SIGHASH_NONE` or `SIGHASH_SINGLE`, then `SIGHASH_ALL` is used.
+
+#### BTC::SIGHASH_NONE = 0x02
+
+All outputs are removed. "I don't care where it goes as long as others pay".
+Note: this is not safe when used with `SIGHASH_ANYONECANPAY`, because then anyone who relays the transaction
+can pick your input and use in his own transaction.
+It's also not safe if all inputs are `SIGHASH_NONE` as well (or it's the only input).
+
+#### BTC::SIGHASH_SINGLE = 0x03
+
+Hash only the output with the same index as the current input.
+Preceding outputs are "nullified", other outputs are removed.
+Special case: if there is no matching output, hash is equal
+`0000000000000000000000000000000000000000000000000000000000000001` (32 bytes)
+
+#### BTC::SIGHASH\_OUTPUT\_MASK = 0x1F
+
+This mask is used to determine one of the first types independently from `SIGHASH_ANYONECANPAY` option:
+
+```
+if (hashtype & SIGHASH_OUTPUT_MASK) == SIGHASH_NONE
+  blank all outputs
+end
+```
+
+#### BTC::SIGHASH_ANYONECANPAY = 0x80
+
+Removes all inputs except for current txin before hashing.
+This allows to sign the transaction outputs without knowing who and how adds other inputs.
+E.g. a crowdfunding transaction with 100 BTC output can be signed independently by any number of people
+and will become valid only when someone combines all inputs in a single transaction to make it valid.
+Can be used together with any of the above types.
+
+