btcruby 0.0.0 → 1.0.0

data/documentation/transaction.md

@@ -0,0 +1,213 @@
+[Index](index.md)
+
+BTC::Transaction
+================
+
+**Transaction** (aka "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` 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.
+
+Transactions are stored within [blocks](block.md) that form the *block chain*.
+
+The first transaction in a [block](block.md) is called *coinbase transaction*.
+It has no inputs and the outputs contain collected mining fees and the mining reward (25 BTC per block as of March 2015).
+
+Constants
+---------
+
+#### CURRENT_VERSION
+
+Current version for all transactions. Equals `1`. 
+
+#### DEFAULT\_FEE\_RATE
+
+Default mining fee rate in satoshis per 1000 bytes. Equals `10000`.
+
+
+Initializers
+------------
+
+#### new(hex: *String*)
+
+Returns a new transaction initialized with a hex-encoded string in [wire format](wire_format.md).
+Raises `ArgumentError` if transaction is incomplete or incorrectly encoded.
+
+#### new(data: *String*)
+
+Returns a new transaction initialized with a binary string in [wire format](wire_format.md).
+Raises `ArgumentError` if transaction is incomplete or incorrectly encoded.
+
+#### new(stream: *IO*)
+
+Returns a new transaction initialized with data in [wire format](wire_format.md) read from a given stream.
+Raises `ArgumentError` if transaction is incomplete or incorrectly encoded.
+
+#### new(*attributes*)
+
+Returns a new transaction with named [attributes](#attributes).
+All attributes are optional and have appropriate default values.
+
+```ruby
+Transaction.new(
+  version: 1,
+  inputs: [...],
+  outputs: [...],
+  lock_time: 0,
+  block_height: 319238,
+  ...
+)
+```
+
+Attributes
+----------
+
+#### version
+
+Version of the transaction. Default value is `BTC::Transaction::CURRENT_VERSION`.
+
+#### inputs
+
+List of [TransactionInput](transaction_input.md) objects. See also `add_input` and `remove_all_inputs`.
+
+#### outputs
+
+List of [TransactionOutput](transaction_output.md) objects. See also `add_output` and `remove_all_outputs`.
+
+#### lock_time
+
+Lock time makes transaction not spendable until a designated time in the future.
+Contains either a block height or a unix timestamp.
+If this value is below [LOCKTIME_THRESHOLD](constants.md),
+then it is treated as a block height. Default value is `0`.
+
+Optional Attributes
+-------------------
+
+These are not derived from transaction binary data, but set from some other source.
+
+#### block_hash
+
+Binary hash of the block at which transaction was included.
+If not confirmed or not available, equals `nil`.
+
+Read-write. Default value is `nil`.
+
+#### block_id
+
+Hex big-endian hash of the block at which transaction was included.
+See [Hash↔ID Conversion](hash_id.md).
+If not confirmed or not available, equals `nil`.
+
+Read-write. Default value is `nil`.
+
+#### block_height
+
+Height of the block at which transaction was included. If not confirmed equals `-1`.
+Note: `block_height` might not be provided by some APIs while `confirmations` may be.
+
+Read-write. Default value is `nil`.
+
+#### block_time
+
+Time of the block at which tx was included (`Time` instance or `nil`).
+
+Read-write. Default value is `nil`.
+
+#### confirmations
+
+Number of confirmations for this transaction (depth in the blockchan).
+Value `0` stands for unconfirmed transaction (stored in mempool). 
+
+Read-write. Default value is `nil`.
+
+#### fee
+
+If available, returns mining fee paid by this transaction.
+If set, `inputs_amount` is updated as (`outputs_amount` + `fee`).
+
+Read-write. Default value is `nil`.
+
+#### inputs_amount
+
+If available, returns total amount of all inputs.
+If set, `fee` is updated as (`inputs_amount` - `outputs_amount`).
+
+Read-write. Default value is `nil`.
+
+#### outputs_amount
+
+Total amount on all outputs (not including fees).
+Always available because [outputs](transaction_output.md) contain their amounts.
+
+Read-only.
+
+
+Instance Methods
+----------------
+
+#### transaction_hash
+
+32-byte transaction hash identifying the transaction.
+
+#### transaction_id
+
+Hex big-endian hash of the transaction. See [Hash↔ID Conversion](hash_id.md).
+
+#### data
+
+Binary representation of the transaction in [wire format](wire_format.md) (aka payload).
+
+#### dictionary
+
+Dictionary representation of transaction ready to be encoded in JSON, PropertyList etc.
+
+#### coinbase?
+
+Returns `true` if this transaction generates new coins.
+
+#### signature\_hash(input\_index: *Integer*, output\_script: *BTC::Script*, hash\_type: *Integer*)
+
+Returns a binary hash for signing a transaction (see [BTC::Key#ecdsa_signature](key.md#ecdsa_signaturehash)).
+You should specify an input index, output [script](script.md) of the previous transaction for that input,
+and an optional [hash type](signature.md) (default is `SIGHASH_ALL`).
+
+#### to_s
+
+Returns a hex representation of the transaction `data`.
+
+#### to_hex
+
+Returns a hex representation of the transaction `data`.
+
+#### dup
+
+Returns a complete copy of a transaction (each input and output is also copied via `dup`).
+
+#### ==
+
+Returns `true` if both transactions have equal binary representation.
+
+#### add_input(*input*)
+
+Adds a [BTC::TransactionInput](transaction_input.md) instance to a list of `inputs`.
+After being added, input will have its `transaction` attribute set to the receiver.
+
+Returns `self`.
+
+#### add_output(*output*)
+
+Adds a [BTC::TransactionOutput](transaction_output.md) instance to a list of `outputs`.
+After being added, output will have its `transaction` attribute set to the receiver.
+
+Returns `self`.
+
+#### remove\_all\_inputs
+
+Removes all [inputs](transaction_input.md) from the transaction and returns `self`.
+
+#### remove\_all\_outputs
+
+Removes all [outputs](transaction_output.md) from the transaction and returns `self`.
+

data/documentation/transaction_builder.md

@@ -0,0 +1,188 @@
+[Index](index.md)
+
+BTC::TransactionBuilder
+=======================
+
+Transaction Builder allows building complex transactions in a convenient and safe manner.
+It handles logic of selecting unspent outputs, calculates mining fees and computes amount for the change output.
+
+Example
+-------
+
+```ruby
+# 0. Create an instance of TransactionBuilder.
+builder = TransactionBuilder.new
+
+# 1. Provide a list of addresses or WIF objects to get unspent outputs from.
+builder.input_addresses = [ "L1uyy5qTuGrVXrmrsvHWHgVzW9kKdrp27wBC7Vs6nZDTF2BRUVwy" ]
+
+# 2. Use a local UTXO index or Chain.com API to fetch unspent outputs for the input addresses.
+builder.unspent_outputs_provider_block = lambda do |addresses, outputs_amount, outputs_size, fee_rate|
+  return array of BTC::TransactionOutput instances...
+end
+
+# 3. Specify payment address and amount
+builder.outputs = [ 
+  TransactionOutput.new(value: 10_000, script: Address.parse("17XBj6iFEsf8kzDMGQk5ghZipxX49VXuaV").script) 
+]
+
+# 4. Specify the change address
+builder.change_address = Address.parse("1CBtcGivXmHQ8ZqdPgeMfcpQNJrqTrSAcG")
+
+# 5. Build the transaction and broadcast it.
+result = builder.build
+tx = result.transaction
+puts tx.to_hex
+
+# => 01000000018689302ea03ef5dd56fb7940a867f9240fa811eddeb0fa4c87ad9ff3728f5e11
+#    000000006b483045022100e280f71106a84a4a1b1a2035eae70266eb53630beab2b59cc...
+```
+
+Result Attributes
+-----------------
+
+Transaction Builder's `build` method returns `BTC::TransactionBuilderResult` instance with the following attributes:
+
+#### transaction
+
+[BTC::Transaction](transaction.md) instance. Each input is either signed (if WIF was used)
+or contains an unspent output's script as its signature_script.
+
+Unsigned inputs are marked using `unsigned_input_indexes` attribute.
+
+#### unsigned\_input\_indexes
+
+List of input indexes that are not signed.
+Empty list means all indexes are signed.
+
+#### fee
+
+Total fee for the composed transaction.
+Equals `inputs_amount` - `outputs_amount`.
+
+#### inputs_amount
+
+Total amount on the inputs.
+
+#### outputs_amount
+
+Total amount on the outputs.
+
+#### change_amount
+
+Amount in satoshis sent to a change address.
+Equals `outputs_amount` - `sent_amount`.
+
+#### sent_amount
+
+Amount in satoshis sent to outputs specified by the user.
+Equals `outputs_amount` - `change_amount`.
+
+
+Attributes
+----------
+
+#### input_addresses
+
+Addresses from which to fetch the inputs. Could be base58-encoded addresses or [WIF](wif.md) strings, or [BTC::Address](address.md) instances.
+
+If any address is a WIF (string or `BTC::WIF` instance), the corresponding input will be
+automatically signed with its private key using `SIGHASH_ALL` [hashtype](signature.md).
+
+Otherwise, the `signature_script` in the input will be set to the output script from unspent output and index of that input will be added to `unsigned_input_indexes`.
+
+#### unspent_outputs
+
+Actual available [BTC::TransactionOutputs](transaction_output.md) to spend.
+If not specified, builder will fetch and remember unspent outputs
+using `unspent_outputs_provider_block`.
+Only necessary inputs will be selected for spending.
+
+If [TransactionOutput#confirmations](transaction_output.md#confirmations) attribute is not `nil`, outputs are sorted
+from oldest to newest, unless `keep_unspent_outputs_order` is set to `true`.
+
+#### unspent\_outputs\_provider\_block
+
+Data-providing block with signature lambda{|addresses, outputs_amount, outputs_size, fee_rate|  [...] }
+
+* `addresses` is a list of BTC::Address instances.
+* `outputs_amount` is a total amount in satoshis to be spent in all outputs (not including change output).
+* `outputs_size` is a total size of all outputs in bytes (including change output).
+* `fee_rate` is a miner's fee per 1000 bytes.
+
+Block returns an array of unspent BTC::TransactionOutput instances with non-nil #transaction_hash and #index.
+
+Note: data provider may or may not use additional parameters as a hint
+to select the best matching unspent outputs. If it takes into account these parameters,
+it is responsible to provide enough unspent outputs to cover the resulting fee.
+
+If `outputs_amount` is 0, all possible unspent outputs are expected to be returned.
+
+#### outputs
+
+An array of `BTC::TransactionOutput` instances determining how many coins to spend and how.
+If the array is empty, all unspent outputs are spent to the change address.
+
+#### change_address
+
+Change address (base58-encoded string or `BTC::Address`).
+Must be specified, but may not be used if change is too small.
+
+#### fee_rate
+
+Miner's fee per kilobyte (1000 bytes).
+Default is `BTC::Transaction::DEFAULT_FEE_RATE`.
+
+#### minimum_change
+
+Minimum amount of change below which transaction is not composed.
+If change amount is non-zero and below this value, more unspent outputs are used.
+If change amount is zero, change output is not even created and this attribute is not used.
+Default value equals `fee_rate`.
+
+#### dust_change
+
+Amount of change that can be forgone as a mining fee if there are no more
+unspent outputs available. If equals zero, no amount is allowed to be forgone.
+
+Default value equals `minimum_change`. This means builder will never fail with "insufficient funds" just because it could not
+find enough unspents for big enough change. In worst case it will forgo the change
+as a part of the mining fee. Set to 0 to avoid wasting a single satoshi.
+
+#### keep\_unspent\_outputs\_order
+
+If true, does not sort `unspent_outputs` by confirmations number.
+Default is `false`, but order will be preserved if `confirmations` attribute is `nil`.
+
+
+Instance Method
+---------------
+
+#### build
+
+Attempts to build a transaction and returns an instance of `BTC::TransactionBuilderResult`. 
+
+Raises a subclass of `TransactionBuilderError` exception.
+
+Errors
+------
+
+#### TransactionBuilderError < BTCError
+
+A base class for all errors used by Transaction Builder.
+
+#### TransactionBuilderMissingChangeAddressError < TransactionBuilderError
+
+Change address is not specified.
+
+#### TransactionBuilderMissingUnspentOutputsError < TransactionBuilderError
+
+Unspent outputs are missing. Maybe because input_addresses are not specified.
+
+#### TransactionBuilderInsufficientFundsError < TransactionBuilderError
+
+Unspent outputs are not sufficient to build the transaction.
+
+
+
+

data/documentation/transaction_input.md

@@ -0,0 +1,133 @@
+[Index](index.md)
+
+BTC::TransactionInput
+=====================
+
+Transaction Input (aka "txin") 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.
+
+Constants
+---------
+
+#### INVALID_INDEX
+
+Invalid index is used in *coinbase* inputs. Equals `0xFFFFFFFF` (`(unsigned int) -1`).
+
+#### MAX_SEQUENCE
+
+Equals `0xFFFFFFFF`.
+
+#### ZERO_HASH256
+
+Equals all-zero 32-byte binary string.
+
+
+Initializers
+------------
+
+#### new(data: *String*)
+
+Returns a new transaction input initialized with a binary string in [wire format](wire_format.md).
+Raises `ArgumentError` if transaction input is incomplete or incorrectly encoded.
+
+#### new(stream: *IO*)
+
+Returns a new transaction input initialized with data in [wire format](wire_format.md) read from a given stream.
+Raises `ArgumentError` if transaction input is incomplete or incorrectly encoded.
+
+#### new(*attributes*)
+
+Returns a new transaction input with named [attributes](#attributes).
+All attributes are optional and have appropriate default values.
+
+```ruby
+TransactionInput.new(
+  previous_id: "d21633ba23f70118185227be58a63527675641ad37967e2aa461559f577aec43",
+  previous_index: 0,
+  signature_script: Script.new << script_signature << pubkey,
+  ...
+)
+```
+
+Attributes
+----------
+
+#### previous_hash
+
+Binary hash of the previous transaction.
+
+#### previous_id
+
+Hex big-endian hash of the previous transaction. See [Hash↔ID Conversion](hash_id.md).
+
+#### previous_index
+
+Index of the previous transaction's output (uint32).
+Default value is `INVALID_INDEX`.
+
+#### signature_script
+
+[BTC::Script](script.md) instance that proves ownership of the previous transaction output.
+We intentionally do not call it "script" to avoid accidental confusion with
+[TransactionOutput#script](transaction_output.md#script).
+
+For *coinase* inputs use `coinbase_data` instead.
+
+#### coinbase_data
+
+Binary string contained in place of `signature_script` in a coinbase input (see `coinbase?`).
+
+Returns `nil` if it is not a coinbase input.
+
+#### sequence
+
+Input sequence (uint32_t). Default is maximum value 0xFFFFFFFF.
+Sequence is used to update a timelocked tx stored in memory of the nodes. It is only relevant when tx lock_time > 0.
+Currently, for DoS and security reasons, nodes do not store timelocked transactions making the sequence number meaningless.
+
+
+Optional Attributes
+-------------------
+
+These are not derived from transaction input’s binary data, but set from some other source.
+
+#### transaction
+
+Optional reference to the owning transaction. It is set on [tx.add_input](transaction.md#add_inputinput) and
+reset to `nil` on [tx.remove_all_inputs](transaction.md#remove_all_inputs).
+
+Default value is `nil`.
+
+#### transaction_output
+
+Optional reference to an [output](transaction_output.md) that this input is spending.
+
+#### value
+
+Optional value in the corresponding output (in satoshis).
+
+Default value is `transaction_output.value` or `nil`.
+
+
+Instance Methods
+----------------
+
+#### data
+
+Binary representation of the transaction input in [wire format](wire_format.md) (aka payload).
+
+#### dictionary
+
+Dictionary representation of transaction input ready to be encoded in JSON, PropertyList etc.
+
+#### coinbase?
+
+Returns `true` if this transaction input belongs to a *coinbase* transaction.
+Coinbase input has no `signature_script` and its `index` equals `INVALID_INDEX`.
+
+
+

data/documentation/transaction_output.md

@@ -0,0 +1,130 @@
+[Index](index.md)
+
+BTC::TransactionOutput
+======================
+
+Transaction Output (aka "txout") is a part of a bitcoin [transaction](transaction.md) that specifies
+destination of the bitcoins being transferred.
+
+Every output has `value` (in satoshis) and `script` (that typically corresponds to an [address](address.md)).
+
+This class is frequently used to specify **unspent outputs** (aka "unspents"). 
+Unspent outputs typically have optional attributes `transaction_hash` and `index` to allow
+creating a corresponding [input](transaction_input.md).
+
+Initializers
+------------
+
+#### new(data: *String*)
+
+Returns a new transaction output initialized with a binary string in [wire format](wire_format.md).
+Raises `ArgumentError` if transaction output is incomplete or incorrectly encoded.
+
+#### new(stream: *IO*)
+
+Returns a new transaction output initialized with data in [wire format](wire_format.md) read from a given stream.
+Raises `ArgumentError` if transaction output is incomplete or incorrectly encoded.
+
+#### new(*attributes*)
+
+Returns a new transaction output with named [attributes](#attributes).
+All attributes are optional and have appropriate default values.
+
+```ruby
+TransactionOutput.new(
+  value: 42 * BTC::COIN,
+  script: Address.parse("1CBtcGivXmHQ8ZqdPgeMfcpQNJrqTrSAcG").script,
+  ...
+)
+```
+
+Attributes
+----------
+
+#### value
+
+Amount in satoshis to be locked in this output.
+
+#### script
+
+An instance of [BTC::Script](script.md) that specifies conditions that allow spending bitcoins.
+
+Typically corresponds to a recipient [address](address.md):
+
+```ruby
+Address.parse("1CBtcGivXmHQ8ZqdPgeMfcpQNJrqTrSAcG").script
+```
+
+Optional Attributes
+-------------------
+
+These are not derived from transaction outputs’s binary data, but set from some other source.
+
+#### transaction
+
+Reference to the owning transaction. It is set on [tx.add_output](transaction.md#add_outputoutput) and
+reset to `nil` in [tx.remove_all_outputs](transaction.md#remove_all_outputs). Default value is `nil`.
+
+#### transaction_hash
+
+Binary hash of the containing transaction. Default value is `nil`.
+
+#### transaction_id
+
+Hex big-endian hash of the containing transaction. See [Hash↔ID Conversion](hash_id.md).
+
+#### index
+
+Index of this output in the containing transaction. Default value is `nil`.
+
+#### block_hash
+
+Binary hash of the block at which containing transaction was included.
+If not confirmed or not available, equals `nil`.
+
+#### block_id
+
+Hex big-endian hash corresponding to `block_hash`. See [Hash↔ID Conversion](hash_id.md).
+
+#### block_height
+
+Height of the block at which containing transaction was included.
+If not confirmed equals `-1`.
+
+Note: `block_height` might not be provided by some APIs while `confirmations` may be.
+Default value is derived from `transaction` if possible or equals `nil`.
+
+#### block_time
+
+Time of the block at which containing transaction was included (`Time` instance or `nil`).
+Default value is derived from `transaction` if possible or equals `nil`.
+
+#### confirmations
+
+Number of confirmations. Default value is derived from `transaction` if possible or equals `nil`.
+
+#### spent
+
+If available, returns whether this output is spent (`true` or `false`).
+Default is `nil`. See also `spent_confirmations`.
+
+#### spent_confirmations
+
+If the containing transaction is spent, contains number of confirmations of the spending transaction.
+
+Returns `nil` if not available or output is not spent.
+
+Returns `0` if spending transaction is not confirmed.
+
+
+Instance Methods
+----------------
+
+#### data
+
+Binary representation of the transaction output in [wire format](wire_format.md) (aka payload).
+
+#### dictionary
+
+Dictionary representation of transaction output ready to be encoded in JSON, PropertyList etc.
+