btcruby 0.0.0 → 1.0.0

data/documentation/constants.md

@@ -0,0 +1,88 @@
+[Index](index.md)
+
+BTC Constants
+=============
+
+These are defined in **constants.rb**.
+
+Units
+-----
+
+#### SATOSHI = 1
+
+Satoshi is the smallest unit representable in Bitcoin [transactions](transaction.md).
+
+#### COIN = 100\_000\_000
+
+One bitcoin equals 100 million satoshis.
+
+#### BIT = 100
+
+1 bit is 100 satoshis (1 millionth of a bitcoin).
+
+
+Network Rules
+-------------
+
+Changing these will result in incompatibility with other nodes.
+
+#### MAX\_BLOCK\_SIZE = 1\_000\_000
+
+The maximum allowed size for a serialized [block](block.md), in bytes.
+
+#### MAX\_BLOCK\_SIGOPS = MAX\_BLOCK\_SIZE/50
+
+The maximum allowed number of signature check operations in a [block](block.md).
+
+#### MAX\_MONEY = 21\_000\_000 * COIN
+
+No amount larger than this (in satoshis) is valid.
+
+#### COINBASE\_MATURITY = 100
+
+Coinbase transaction outputs can only be spent after this number of new blocks.
+
+#### LOCKTIME\_THRESHOLD = 500\_000\_000
+
+Threshold for [BTC::Transaction#lock_time](transaction.md): below this value it is interpreted 
+as a [block](block.md) number, otherwise as UNIX timestamp.
+
+#### BIP16\_TIMESTAMP = 1333238400
+
+[P2SH](p2sh.md) BIP16 didn't become active until April 1, 2012.
+All [transactions](transaction.md) before this timestamp should not be verified with P2SH rule.
+
+#### MAX\_SCRIPT\_SIZE = 10000
+
+Scripts longer than 10K bytes are invalid.
+
+#### MAX\_SCRIPT\_ELEMENT\_SIZE = 520
+
+Maximum number of bytes per "pushdata" [opcode](opcode.md).
+
+#### MAX\_KEYS\_FOR\_CHECKMULTISIG = 20
+
+Number of [public keys](key.md) allowed for [OP_CHECKMULTISIG](opcode.md).
+
+#### MAX\_OPS\_PER\_SCRIPT = 201
+
+Maximum number of [operations](opcode.md) allowed per [script](script.md) (excluding pushdata operations and OP_*N*).
+Multisig operation additionally increases count by a number of pubkeys.
+
+
+Soft Rules
+----------
+
+Can bend these without becoming incompatible with everyone.
+
+#### MAX\_INV\_SZ = 50000
+
+The maximum number of entries in an 'inv' protocol message.
+
+#### MAX\_BLOCK\_SIZE\_GEN = MAX\_BLOCK\_SIZE / 2
+
+The maximum size for mined blocks.
+
+#### MAX\_STANDARD\_TX\_SIZE = MAX\_BLOCK\_SIZE\_GEN / 5
+
+The maximum size for transactions we're willing to relay/mine.

data/documentation/data.md

@@ -0,0 +1,54 @@
+[Index](index.md)
+
+BTC::Data
+=========
+
+`BTC::Data` module implements common routines dealing with binary strings.
+All functions are also available as methods of `BTC::Data` object.
+
+Module Functions
+----------------
+
+#### random_data(length = 32)
+
+Returns a cryptographically secure random binary string of a given length. Default length is 32 bytes.
+
+#### data\_from\_hex(string)
+
+Returns a binary string decoded from a hex-encoded string.
+
+Raises `FormatError` if argument is not a valid hex string.
+
+#### hex\_from\_data(string)
+
+Returns a hex-encoded string.
+
+#### bytes\_from\_data(string)
+#### bytes\_from\_data(string, offset: 0, limit: nil)
+#### bytes\_from\_data(string, range: nil)
+
+Returns an array of bytes from a given string.
+
+If `offset` is specified, returns bytes starting with a given offset.
+
+If `limit` is specified, limits number of bytes accordingly.
+
+If `range` is specified, returns an array of bytes within the specified range.
+
+#### data\_from\_bytes(bytes)
+
+Returns a binary string made from the given array of bytes (integers).
+
+#### ensure\_ascii\_compatible\_encoding(string, options = nil)
+
+Returns `string` as-is if it is ASCII-compatible (that is, if you are interested in 7-bit characters exposed as `#bytes`).
+If it is not, attempts to transcode to UTF8 replacing invalid characters if there are any.
+
+If `options` are not specified, uses safe defaults: replaces unknown characters with a standard character.
+
+If `options` are specified, they are used as-is for `String#encode` method.
+
+#### ensure\_binary\_encoding(string)
+
+Returns string as-is if it is already encoded in binary encoding (aka BINARY or ASCII-8BIT).
+If it is not, converts to binary by calling standard method `#b`.

data/documentation/diagnostics.md

@@ -0,0 +1,90 @@
+[Index](index.md)
+
+BTC::Diagnostics
+================
+
+Diagnostics provides extensive details of inner workings of various algorithms. 
+For instance, when script is parsed and detects non-canonical encoding of certain elements,
+it is not an error condition, but an unusual case that can be important for debugging.
+
+You can wrap any piece of code in `Diagnostics.current.record { ... }` to collect all diagnostic messages
+or use `Diagnostics.current.trace { ... }` to output all the messages to STDERR.
+
+Class Method
+------------
+
+#### current
+
+An instance of `BTC::Diagnostics` unique to the current thread.
+
+
+Instance Methods
+----------------
+
+#### last_message
+
+Returns the latest recorded message. See `add_message`.
+
+#### last_info
+
+Returns the latest recorded info object associated with the latest message. See `add_message`.
+
+#### last_item
+
+Returns the `Diagnostics::Item` object that contains latest message and info.
+
+#### add_message(*message*, info: nil)
+
+Records a `message` (String) with an optional `info` object. 
+
+When executed within a `trace {...}` block, `message` is written to STDERR or another stream specified in `trace`.
+
+When executed within a `record {...}` block, an `Item` containing both `message` and `info` is added to an array returned from `record`.
+
+#### record { ... }
+
+Returns an array of all `Item` instances recorded by `add_message` within the block.
+
+```ruby
+Diagnostics.current.record do
+  Diagnostics.current.add_message("Hello")
+  Diagnostics.current.add_message("world")
+end.map(&:to_s)
+```
+
+```
+["Hello", "world"]
+```
+
+#### trace(*stream* = $stderr) { ... }
+
+Writes every recorded message to a given stream. Default stream is `$stderr`.
+
+```ruby
+Diagnostics.current.trace do
+  Diagnostics.current.add_message("Hello")
+  Diagnostics.current.add_message("world")
+end
+```
+
+```
+Hello
+world
+```
+
+Diagnostics::Item
+-----------------
+
+Item class represents a pair of `message` (String) and an arbitrary `info` object.
+
+#### message
+
+Message string.
+
+#### info
+
+Additional object of arbitrary type. Default value is `nil`.
+
+#### to_s
+
+Returns `message`.

data/documentation/extensions.md

@@ -0,0 +1,76 @@
+[Index](index.md)
+
+Core Extensions
+===============
+
+Core Extensions are convenience methods available on standard classes like `String`. 
+We do not extend core classes by default to avoid conflicts with other libraries and your own extensions. 
+To enable convenience methods, include `btcruby/extensions.rb` in your application.
+
+Extensions are automatically available in BTCRuby interactive console `bin/console` and in unit tests.
+
+String Extensions
+-----------------
+
+#### to\_wif(network: *BTC::Network*, public\_key\_compressed: *false|true*)
+
+Converts a binary string representing a 32-byte private key to [WIF](wif.md) format.
+
+If `network` is not specified, [BTC::Network.default](network.md#default) is used.
+
+If `public_key_compressed` is not specified, `false` is used.
+
+
+#### from_wif
+
+Converts [WIF-encoded](wif.md) string to a raw 32-byte [private key](key.md#private_key).
+Raises `FormatError` if the receiver is not a valid WIF-encoded string.
+
+#### to_hex
+
+Converts a binary string to a hex-encoded string.
+
+#### from_hex
+
+Converts a hex-encoded string to a binary string. 
+Raises `FormatError` if the receiver is not a valid hex-encoded string.
+
+#### sha1
+
+Returns a binary string compressed using [SHA-1](http://en.wikipedia.org/wiki/SHA-1) algorithm.
+
+#### sha256
+
+Returns a binary string compressed using [SHA-256](http://en.wikipedia.org/wiki/SHA-2) algorithm.
+
+#### sha512
+
+Returns a binary string compressed using [SHA-512](http://en.wikipedia.org/wiki/SHA-2) algorithm.
+
+#### ripemd160
+
+Returns a binary string compressed using [RIPEMD-160](http://en.wikipedia.org/wiki/RIPEMD) algorithm.
+
+#### hash256
+
+Returns a binary string compressed using two passes of [SHA-256](http://en.wikipedia.org/wiki/SHA-256) algorithm. Known in Bitcoin as *Hash256*.
+
+#### hash160
+
+Returns a binary string compressed using composition `ripemd160(sha256(string))`. Known in Bitcoin as *Hash160*.
+
+#### hmac_sha256(key: *String*)
+
+Returns a result of [HMAC](http://en.wikipedia.org/wiki/Hash-based_message_authentication_code) using [SHA-256](http://en.wikipedia.org/wiki/SHA-2) hash using `self` as data.
+
+#### hmac_sha256(data: *String*)
+
+Returns a result of [HMAC](http://en.wikipedia.org/wiki/Hash-based_message_authentication_code) using [SHA-256](http://en.wikipedia.org/wiki/SHA-2) hash using `self` as key.
+
+#### hmac_sha512(key: *String*)
+
+Returns a result of [HMAC](http://en.wikipedia.org/wiki/Hash-based_message_authentication_code) using [SHA-512](http://en.wikipedia.org/wiki/SHA-2) hash using `self` as data.
+
+#### hmac_sha512(data: *String*, key: *String*)
+
+Returns a result of [HMAC](http://en.wikipedia.org/wiki/Hash-based_message_authentication_code) using [SHA-512](http://en.wikipedia.org/wiki/SHA-2) hash using `self` as key.

data/documentation/hash_functions.md

@@ -0,0 +1,58 @@
+[Index](index.md)
+
+BTC::HashFunctions
+==================
+
+Bitcoin uses various hash functions, all of which are available in the module `BTC::HashFunctions`.
+All functions take binary string arguments and return binary strings. 
+Use [hex conversion methods](data.md) to convert string to/from hex encoding if needed.
+
+You typically access these via `BTC` object:
+
+```ruby
+>> BTC.sha256("correct horse battery staple")
+=> "\xc4\xbb\xcb\x1f..."
+```
+
+If you include [Core Extensions](extensions.md), you can use these and some other functions directly on the String:
+
+```ruby
+>> "correct horse battery staple".sha256.to_hex
+=> "c4bbcb1fbec99d65bf59d85c8cb62ee2db963f0fe106f483d9afa73bd4e39a8a"
+```
+
+Module Functions
+----------------
+
+#### sha1(*string*)
+
+Returns a binary string compressed using [SHA-1](http://en.wikipedia.org/wiki/SHA-1) algorithm.
+
+#### sha256(*string*)
+
+Returns a binary string compressed using [SHA-256](http://en.wikipedia.org/wiki/SHA-2) algorithm.
+
+#### sha512(*string*)
+
+Returns a binary string compressed using [SHA-512](http://en.wikipedia.org/wiki/SHA-2) algorithm.
+
+#### ripemd160(*string*)
+
+Returns a binary string compressed using [RIPEMD-160](http://en.wikipedia.org/wiki/RIPEMD) algorithm.
+
+#### hash256(*string*)
+
+Returns a binary string compressed using two passes of [SHA-256](http://en.wikipedia.org/wiki/SHA-256) algorithm. Known in Bitcoin as *Hash256*.
+
+#### hash160(*string*)
+
+Returns a binary string compressed using composition `ripemd160(sha256(string))`. Known in Bitcoin as *Hash160*.
+
+#### hmac_sha256(data: *String*, key: *String*)
+
+Returns a result of [HMAC](http://en.wikipedia.org/wiki/Hash-based_message_authentication_code) using [SHA-256](http://en.wikipedia.org/wiki/SHA-2) hash.
+
+#### hmac_sha512(data: *String*, key: *String*)
+
+Returns a result of [HMAC](http://en.wikipedia.org/wiki/Hash-based_message_authentication_code) using [SHA-512](http://en.wikipedia.org/wiki/SHA-2) hash.
+

data/documentation/hash_id.md

@@ -0,0 +1,22 @@
+[Index](index.md)
+
+Hash ↔ ID Conversion
+======================
+
+[Transactions](transaction.md) and [blocks](block.md) are identified by hashes of their binary contents.
+In practice these hashes are typically presented as hex-encoded big-endian 256-bit integers which we call *IDs*.
+*Transaction ID* and *Block ID* are computed by reversing the bytes of the original binary hash and then encoding it in hex. 
+
+Most of the time, each object that exposes a binary *hash* attribute, also exposes a corresponding *id* attribute.
+However, if you need to manually convert a *hash* to *id* or the other way around, use the following methods on the `BTC` object.
+
+Functions
+---------
+
+#### BTC.hash\_from\_id(*hex\_string*)
+
+Returns a binary hash string for a given hex string.
+
+#### BTC.id\_from\_hash(*hash*)
+
+Returns a hex-encoded identifier for a given binary hash string.

data/documentation/index.md

@@ -0,0 +1,230 @@
+BTCRuby Reference
+=================
+
+Find your topic in the index, or refer to one of the examples below.
+
+Classes and Modules
+-------------------
+
+Bitcoin Data Structures                        | Utilities                           | Crypto
+:----------------------------------------------|:------------------------------------|:--------------------------
+[Constants](constants.md)                      | [Base58](base58.md)                 | [HashFunctions](hash_functions.md)
+[Address](address.md)                          | [Core Extensions](extensions.md)    | [Key](key.md)
+↳ [PublicKeyAddress](p2pkh.md)                 | [Data](data.md)                     | [Keychain](keychain.md)
+↳ [ScriptHashAddress](p2psh.md)                | [Diagnostics](diagnostics.md)       | [OpenSSL](openssl.md)
+↳ [WIF](wif.md)                                | [Hash↔ID Conversions](hash_id.md)   |
+[Block](block.md)                              | [ProofOfWork](proof_of_work.md)     |
+[BlockHeader](block_header.md)                 | [WireFormat](wire_format.md)        |
+[Network](network.md)                          |                                     |
+[Opcode](opcode.md)                            |                                     |
+[Script](script.md)                            |                                     |
+[Signatures and Hash Types](signature.md)      |                                     |
+[Transaction](transaction.md)                  |                                     |
+[TransactionInput](transaction_input.md)       |                                     |
+[TransactionOutput](transaction_output.md)     |                                     |
+[TransactionBuilder](transaction_builder.md)   |                                     |
+
+Glossary
+--------
+
+**[Address](address.md)** is a compact identifier that represents a destination for a Bitcoin payment.
+To parse addresses use base class [BTC::Address](address.md). To encode addresses use subclasses [BTC::PublicKeyAddress](p2pkh.md) and [BTC::ScriptHashAddress](p2sh.md).
+
+**[Base58 encoding](base58.md)** is used to encode Bitcoin [addresses](address.md),
+private keys in [WIF](wif.md) and extended keys for [BIP32 keychains](keychain.md).
+
+**[Blocks](block.md)** and **[Block Headers](block_header.md)** form a block chain that contains [transactions](transaction.md).
+
+**[BIP32](keychain.md)** ("HD Wallets") is a standard for deriving series of [keys](key.md) or [addresses](address.md) from a single seed.
+Use [BTC::Keychain](keychain.md) class to decode extended public and private keys (“xpubs” and “xprvs”) and derive chains of keys.
+
+**[Data](data.md)** is what we call a binary string. BTCRuby uses binary strings by default.
+Use methods defined in [BTC::Data](data.md) namespace to convert strings between hex and binary and access raw bytes in a safe manner.
+
+**[Hash functions](hash_functions.md)** used in Bitcoin are accessible via `BTC` namespace: `BTC.hash256`, `BTC.hash160`, `BTC.sha256` and so on.
+
+**[Input](transaction_input.md)** is a part of a bitcoin [transaction](transaction.md) that
+unlocks bitcoins stored in the [outputs](transaction_output.md) of the previous transactions.
+Every input contains a reference to some output (transaction hash and a numeric index of the output)
+and a [signature script](script.md) that typically contains [signatures](key.md) and other data
+to satisfy conditions defined by the corresponding output script.
+
+**[Keys](key.md)** allow signing transactions and verifying existing signatures.
+Class [BTC::Key](key.md) encapsulates a pair of public and private keys (or only a public key)
+and provides methods to sign transactions and verify signatures.
+
+**[Keychain](keychain.md)** is a chain of [keys](key.md) generated from a single seed
+(or *extended key*) by a mechanism defined in BIP32.
+
+**[Opcode](opcode.md)** is a basic unit of a [script](script.md). It could represent a piece of binary data
+(e.g. a [signature](signature.md)) or an operation on data (e.g. signature verification).
+See [BTC::Opcode](opcode.md) class for a list of available opcodes and related conversion methods.
+
+**[Output](transaction_output.md)** is a part of a bitcoin [transaction](transaction.md) that specifies
+destination of the bitcoins being transferred. Every output has an amount (in satoshis) and a script (that typically corresponds to an [address](address.md)).
+
+**[P2PKH](p2pkh.md)** (pay-to-pubkey-hash) is a classic type of [address](address.md) that
+compresses a public [key](key.md) in a 20-byte hash value. P2PKH-addresses start with "1" on mainnet
+and "n" or "m" on testnet. Use [BTC::PublicKeyAddress](p2pkh.md) class to encode these addresses.
+
+**[P2SH](p2sh.md)** (pay-to-script-hash) is a type of [address](address.md) that represents an arbitrary [script](script.md) as a single 20-byte hash.
+P2SH-address starts with "3" on mainnet and "2N" or "2M" on testnet. Use [BTC::ScriptHashAddress](p2sh.md) class to encode these addresses.
+
+**[Script](script.md)** is a predicate consisting of [opcodes](opcode.md) that defines control
+over bitcoins in a [transaction output](transaction_output.md) or satisfies a predicate when
+unlocking (spending) bitcoins in a [transaction input](transaction_input.md). 
+To create and inspect scripts, use [BTC::Script](script.md) class.
+
+**[Transaction](transaction.md)** (abbreviated "tx") is an object that represents transfer of bitcoins from one or more [inputs](transaction_input.md) to one or more [outputs](transaction_output.md). Use [BTC::Transaction](transaction.md) class to inspect transactions or create them transactions manually. To build transaction we recommend using [BTC::TransactionBuilder](transaction_builder.md), which takes care of a lot of difficulties and exposes easy to use, yet powerful enough API.
+
+**[Transaction ID](transaction.md)** (abbreviated "txid") is a reversed hex representation of transaction hash. To convert between IDs and hashes of transactions and blocks, use `BTC.hash_from_id` and `BTC.id_from_hash` methods.
+
+**[Transaction Builder](transaction_builder.md)** is a high-level API to build [transactions](transaction,md). It selects unspent [outputs](transaction_output.md), prepares correct [signature scripts](script.md), computes mining fees and takes care of the change.
+
+**[WIF](wif.md)** (Wallet Import Format aka "sipa format") is used to encode a single [private key](key.md) in [Base58check](base58.md) encoding.
+
+**[Wire Format](wire_format.md)** is a low-level binary format to encode network messages. Used to encode transactions and blocks. Higher-level objects expose `data` method that takes care of this encoding, but if you need to compose or parse some custom messages, use [BTC::WireFormat](wire_format.md) class.
+
+
+Examples
+--------
+
+### 1. Generating a Bitcoin address
+
+This example demonstrates how to generate a key and get its address.
+
+```ruby
+key = BTC::Key.random
+
+puts key.to_wif # private key in WIF format
+# => L4RqZhbn2VsVgy2wCWW8kUPpA4xEkH7WbfPtj1MdFug5MayHzLeT
+
+puts key.address.to_s # public address
+# => 1MFqAcAxNsAKj5e6yksZCCyfNukSdDGsEY
+
+puts key.to_wif(network: BTC::Network.testnet)
+# => cUnq2cbdTZZkrQWCavKG7ntsnJFeQjDCfhYMqRp8m2L5cL1yHDmc
+
+puts key.address(network: BTC::Network.testnet).to_s
+# => n1mnTfFwBtbaWC7ihKqw28BzEuM9YqxRyw
+```
+
+
+### 2. Making Transactions
+
+Transaction builder helps composing arbitrary transactions using just keys or unspent outputs.
+It takes care of computing a proper change amount, adding fees and signing inputs.
+It is also highly customizable, so you may use it for very complex transactions.
+
+```ruby
+builder = BTC::TransactionBuilder.new
+
+# 1. Provide a list of addresses to get unspent outputs from.
+#    If address is a WIF instance, it will be used to sign corresponding input
+#    If address is a public address (or P2SH), its input will remain unsigned.
+builder.input_addresses = [ "L1uyy5qTuGrVXrmrsvHWHgVzW9kKdrp27wBC7Vs6nZDTF2BRUVwy" ]
+
+# 2. Use external API (e.g. Chain.com) to fetch unspent outputs for the input addresses.
+#    In this example we simply hard-code a single unspent output.
+#    Note: transaction ID and output index must be provided.
+builder.unspent_outputs_provider_block = lambda do |addresses, outputs_amount, outputs_size, fee_rate|
+  txout = BTC::TransactionOutput.new(
+    value: 50_000,
+    script: BTC::PublicKeyAddress.with_string("17XBj6iFEsf8kzDMGQk5ghZipxX49VXuaV").script,
+    transaction_id: "115e8f72f39fad874cfab0deed11a80f24f967a84079fb56ddf53ea02e308986",
+    index: 0
+  )
+  [ txout ]
+end
+
+# 3. Specify payment address and amount
+builder.outputs = [ BTC::TransactionOutput.new(
+                        value: 10_000,
+                        script: BTC::Address.parse("17XBj6iFEsf8kzDMGQk5ghZipxX49VXuaV").script) ]
+
+# 4. Specify the change address
+builder.change_address = BTC::Address.parse("1CBtcGivXmHQ8ZqdPgeMfcpQNJrqTrSAcG")
+
+# 5. Build the transaction and broadcast it.
+result = builder.build
+tx = result.transaction
+puts tx.to_hex
+
+# => 01000000018689302ea03ef5dd56fb7940a867f9240fa811eddeb0fa4c87ad9ff3728f5e11
+#    000000006b483045022100e280f71106a84a4a1b1a2035eae70266eb53630beab2b59cc8cf
+#    f40b1a5bdbb902201dcbae9bb12730fe5563dc37e3a33e064f2efa78ba0af5c0179187aece
+#    180b6c0121029f50f51d63b345039a290c94bffd3180c99ed659ff6ea6b1242bca47eb93b5
+#    9fffffffff0210270000000000001976a91447862fe165e6121af80d5dde1ecb478ed17056
+#    5b88ac30750000000000001976a9147ab89f9fae3f8043dcee5f7b5467a0f0a6e2f7e188ac
+#    00000000
+```
+
+
+### 3. Creating a transaction manually
+
+To manually create a transaction, you will need to specify raw inputs,
+compute the signature and compose a signature script for each input and
+take care of calculating fees and change.
+
+```ruby
+include BTC
+
+tx = Transaction.new
+
+# 1. Add a raw input with previous transaction ID and output index.
+tx.add_input(TransactionInput.new(
+                previous_id: "aa94ab02c182214f090e99a0d57021caffd0f195a81c24602b1028b130b63e31",
+                previous_index: 0))
+
+# 2. Add a raw output with a script
+tx.add_output(TransactionOutput.new(
+                value: 100_000,
+                script: PublicKeyAddress.with_string("1CBtcGivXmHQ8ZqdPgeMfcpQNJrqTrSAcG").script))
+
+# 3. Get the private key from WIF
+key = Key.new(wif: "L1uyy5qTuGrVXrmrsvHWHgVzW9kKdrp27wBC7Vs6nZDTF2BRUVwy")
+
+# 4. Sign the input (assuming it links to an output with address 18oxCAnbuKHDjP7KzLBDj8mLjggDBjE1Q9)
+hashtype = BTC::SIGHASH_ALL
+sighash = tx.signature_hash(input_index: 0,
+                            output_script: Address.parse("18oxCAnbuKHDjP7KzLBDj8mLjggDBjE1Q9").script,
+                            hash_type: hashtype)
+tx.inputs[0].signature_script = Script.new << (key.ecdsa_signature(sighash) + WireFormat.encode_uint8(hashtype)) << key.public_key
+
+# Get transaction data and broadcast it
+puts tx.data # => raw binary data
+puts tx.to_hex # hex-encoded data
+# => 0100000001313eb630b128102b60241ca895f1d0ffca2170d5a0990e094f2182c102ab94aa
+#    000000006a473044022039148258144202301221a305adb38ce0a182ecb4055c6015cdd735
+#    8372d7ad6d022008aa259c87177f0e4e887dd0947c57fd140eb8f8a826f14ef8389dbc26ef
+#    a7b20121029f50f51d63b345039a290c94bffd3180c99ed659ff6ea6b1242bca47eb93b59f
+#    ffffffff01a0860100000000001976a9147ab89f9fae3f8043dcee5f7b5467a0f0a6e2f7e1
+#    88ac00000000
+```
+
+
+### 4. Creating a P2SH multisig address
+
+To create a P2SH multisig address you will need a set of public keys.
+In the example below we generate three random keys and compose 2-of-3 multisig script
+which is then transformed into a P2SH address. To redeem from this address you will need
+not only two signatures, but also the original multisig script.
+
+```ruby
+keys = [BTC::Key.random, BTC::Key.random, BTC::Key.random]
+pubkeys = keys.map(&:public_key)
+
+multisig_script = BTC::Script.multisig(public_keys: pubkeys, signatures_required: 2)
+puts multisig_script.to_s # => "OP_2 02c008dc... 03cab527... 024ac920... OP_3 OP_CHECKMULTISIG"
+
+p2sh_script = multisig_script.p2sh_script
+puts p2sh_script.to_s # => "OP_HASH160 a6bdcfcac410d1c1acbf34701da382ca34a691a3 OP_EQUAL"
+
+address = p2sh_script.standard_address
+puts address.to_s # => 3GtfUjaNBqG9wjw3CCgbxLUrbjtSDg4nDf
+```
+
+
+
+
+