bitcoinj.github.io - Working with transactions

Working with transactions

Bitcoinj.github.io Spined HTML

Working with transactions Introduction Getting started DocumentationPolityWorking with transactions Introduction What is a transaction? The Transaction matriculationConvictionlevels Understanding difficulty and conviction How transactions can be used Direct transfer Participation in contracts Working with transactions Introduction Transactions are the fundamental atoms of the Bitcoin protocol. They encapsulate a requirement upon some value, and the conditions needed for that value to itself later be claimed. This vendible will discuss: What a transaction is The Transaction matriculation and what it gives you Transaction confidences Different ways in which transactions can be used What is a transaction? Transactions are, at heart, a hodgepodge of inputs and outputs. They moreover have a lock time, which is not used in the current Bitcoin network, and a few shit of metadata only represented in bitcoinj like when the transaction was last seen and a conviction measurement. All this is represented using the Transaction class. An output is a data structure specifying a value and a script, conventionally tabbed the scriptPubKey. An output allocates some of the value gathered by the transactions inputs to a particular program. Anyone who can satisfy the program (make it return true) is unliable to requirement that outputs value in their own transaction. Output scripts most often trammels signatures versus public keys, but they can do many other things. An input is a data structure that contains a script, which in practice is just a list of byte arrays, and an outpoint, which is a reference to an output of flipside transaction.ConsideringBitcoin identifies transactions by their hash, an outpoint is therefore a (hash, index) pair in which the alphabetize simply identifies which output in the given transaction is intended. We say the input is unfluctuating to an output. Input scripts, conventionally tabbed scriptSigs can theoretically contain any script opcodes, but considering the programs are run with no input there is little point in doing that, therefore, real input scripts only overly push constants like signatures and keys onto the stack. Inputs moreover contain sequence numbers. Sequence numbers are not currently used on the Bitcoin network and are not exposed by bitcoinj. They exist to support contracts. The mismatch, if any, between the value gathered by a transactions inputs and spent by its outputs is tabbed the fee. Obviously, a transaction that has increasingly value in its outputs than gathered by its inputs is considered invalid, but the reverse is not true. Value not re-allocated can be legitimately personal by whoever successfully mines a woodcut containing that transaction. Note that an input does not contain a value field. To find the value of an input, you must trammels the value of its unfluctuating output. That implies that given a standalone transaction, you cannot know what its fee is, unless you moreover have all of the transactions its inputs connect to. Transactions can be serialized and either unconcentrated wideness the P2P network, in which specimen miners may start trying to include it in a block, or passed virtually outside the network using other protocols. The Transaction matriculation The Transaction matriculation lets you deserialize, serialize, build and inspect transactions. It moreover helps you track interesting metadata well-nigh a transaction such as which blocks (if any) it has been included in, and how much conviction you can have that the transaction won’t be reversed/double spent. Inputs are represented with the TransactionInput class, and outputs are of undertow handled by the TransactionOutput class. Inputs can be unsigned, in which specimen the transaction won’t be considered valid by the network, but the intermediate state can be useful to work with sometimes.Worldwidetasks: Access inputs and outputs using getInputs(), getOutputs(), addInput() and addOutput(). Note that addInput() has two forms, one which takes a TransactionInput - logical enough. The other takes a TransactionOutput, and will create an unsigned input for you that connects to that output. Sign the transactions inputs with signInputs(). Currently you must unchangingly pass SigHash.ALL as the first parameter. Other types of SigHash flags will wilt supported in future. They are used for contracts. This method moreover requires a wallet that contains the keys used by the inputs unfluctuating outputs. If you don’t have the private keys, then obviously you cannot requirement the value. Find which blocks the transaction appears in using getAppearsInHashes().Consideringthe transaction only stores the hashes of the woodcut headers, you may need to use a populated BlockStore to get the woodcut data itself. Learn well-nigh the state of the transaction in the uniting using getConfidence. This returns a TransactionConfidence object representing various shit of data well-nigh when and where the transaction was included into the woodcut chain.Convictionlevels A transaction has an associated confidence. This is data you can use to summate the probability of the transaction stuff reversed (double spent). This is unchangingly a risk in Bitcoin although at upper network speeds, the probability becomes extremely low, certainly relative to traditional payment systems.Convictionis modelled with the TransactionConfidence object. You can get one by calling Transaction.getConfidence().Convictiondata does not exist in Bitcoin serialization, but will survive Java and protobuf serialization. A conviction object has one of several states: If BUILDING, then the transaction is included in the weightier uniting and your conviction in it is increasing. If PENDING, then the transaction is unconfirmed and should be included shortly as long as it is stuff unconcentrated from time to time and is considered valid by the network. A pending transaction will be spoken if the containing wallet has been tying to a live PeerGroup using PeerGroup.addWallet(). You can estimate how likely the transaction is to be included by measuring how many nodes signify it without sending it to one peer, using TransactionConfidence.numBroadcastPeers(). Or if you saw it from a trusted peer, you can seem it’s valid and will get mined sooner or later as well. If DEAD, then it ways the transaction won’t personize unless there is flipside re-org, considering some other transaction is spending one of its inputs. Such transactions should be alerted to the user so they can take action, eg, suspending shipment of goods if they are a merchant. UNKNOWN is used if we have no information well-nigh the conviction of this transaction, considering for example it has been deserialized from a Bitcoin structure but not unconcentrated or seen in the uniting yet. UNKNOWN is the default state. The conviction type, misogynist via TransactionConfidence.getConfidenceType(), is a unstipulated statement of the transactions state. You can get a increasingly precise view using getters on the object. For example, in the BUILDING state, getDepthInBlocks() should tell you how tightly veiled the transaction is, in terms of blocks. The deeper it is veiled in the chain, the less endangerment you have of the transaction stuff reversed. Depth in blocks is easy to understand and roughly corresponds to how long the transaction has been confirmed for (1 woodcut == 10 minutes on average). However, this is not a stable measure of how much effort it takes to reverse a transaction considering the value of work washed-up on a woodcut varies over time, depending on how much mining is happening, which itself depends on the mart rate (vs the dollar/euro/etc). Understanding difficulty and conviction The most worldwide reason you are interested in conviction is you wish to measure the risk of losing money that was sent to you, for example, to wait dispatching of goods or provision of services. The Bitcoin polity uses a rule of thumb of zero confirmations for things that aren’t of much value like MP3s or ebooks, one or two blocks for things (10-20 minutes) for things that stand a risk of a double spend attack, or 6 blocks (an hour) for where waddle solid certainty is required, like with currency exchanges. In practice, reports of merchants suffering double-spend fraud are rare so this discussion is somewhat theoretical. You’ll notice that the rules of thumb quoted whilom are expressed as blocks, not work done. So if the mart rate and thus mining falls, 2 blocks provides less warranty than before, meaning you may wish to wait longer. Conversely if the mart rate rises, mining worriedness will increase, meaning you can wait less time surpassing a transaction is valid, resulting in happier customers. This is why we moreover provide a way to measure conviction as work done. How transactions can be used The most worldwide and obvious way to use transactions is to: Download them into your wallet from the woodcut uniting or network broadcasts Create spends and then unconcentrated them However there are many other possibilities. Direct transfer It’s possible to send someone money by directly giving them a transaction, which they can then unconcentrated at their leisure, or remoter modify. These use cases aren’t well supported today, but in future may wilt a worldwide way to use Bitcoin. Participation in contracts Contracts indulge for a variety of low trust trades to take place, mediated by the Bitcoin network. By thoughtfully constructing transactions with particular scripts, signatures and structures you can have low-trust dispute mediation, coins locked to wrong-headed conditions (eg, futures contracts), warranty contracts, smart property and many other possibilities. You can learn increasingly well-nigh this topic in the vendible WorkingWithContracts.