bitcoinj.github.io - Working with contracts

Working with contracts

Bitcoinj.github.io Spined HTML

Working with contracts Introduction Getting started Documentation Community Working with contracts Introduction Creating multi-signature outputs Partial signing Other SIGHASH modes P2SH (pay to script hash) Working with contracts How to diamond and implement contract based applications. Introduction Contracts are an heady full-length of Bitcoin that has opened up a new research field - using flexible digital money to produce compelling and innovative applications. The linked wiki page contains some examples of what can be done, but it can sometimes be unclear how to convert them into code. In this article, we’ll squint at a few worldwide techniques that are used when implementing contract-based applications. It assumes you’re once familiar with how the Bitcoin protocol works and have understood the theory on the contracts page - if something is unclear, please ask on the mailing list. Creating multi-signature outputs Contracts very often use multi-signature outputs in order to intrust value to a group of users … typically, the participants in the contract protocol. Multi-signature outputs are easy to create with bitcoinj. For the next few examples, we will not be using P2SH (pay to script hash), so the set of keys chosen won’t be representable as a 3… type address. We’ll learn increasingly well-nigh P2SH at the end. Let’s see how to do it: // Create a random key. ECKey clientKey = new ECKey(); // We get the other parties public key from somewhere ... ECKey serverKey = new ECKey(null, publicKeyBytes); // Prepare a template for the contract. Transaction contract = new Transaction(params); List<ECKey> keys = ImmutableList.of(clientKey, serverKey); // Create a 2-of-2 multisig output script. Script script = ScriptBuilder.createMultiSigOutputScript(2, keys); // Now add an output for 0.50 bitcoins that uses that script. Coin value = Coin.valueOf(0, 50); contract.addOutput(amount, script); // We have said we want to make 0.5 coins controlled by us and them. // But it's not a valid tx yet considering there are no inputs. SendRequest req = SendRequest.forTx(contract); wallet.completeTx(req); // Could throw InsufficientMoneyException //Unconcentratedand wait for it to propagate wideness the network. // It should take a few seconds unless something went wrong. peerGroup.broadcastTransaction(req.tx).get(); Alright, now we have unconcentrated the transaction - note that in some contract protocols, you don’t unquestionably unconcentrated right away. The example whilom just does it for completeness. But how do we get the money when again? For that, we need a transaction that includes two signatures, one calculated by us, and one by them. Partial signing A worldwide requirement when implementing contract protocols is to pass virtually and sign incomplete transactions. The Wallet matriculation doesn’t know how to handle outputs that aren’t fully owned by it. So we’ll have to sign the spending transaction ourselves. The key point to withstand in mind is that when you sign a transaction, what you unquestionably sign is only parts of that transaction. Which parts are controlled by the signature hash (sighash) flags. But no matter which flags you select, the contents of input scripts are never signed. Indeed that must be the case, considering otherwise you could never build a transaction - the act of signing the second input would modify the version of the transaction signed by the first, breaking the signature. This ways that signatures can be calculated and sent between variegated parties in a contract, then inserted into a transaction to make it valid. Let’s squint at what the server-side lawmaking might squint like: // Assume we get the multisig transaction we're trying to spend from // somewhere, like a network connection. ECKey serverKey = ....; Transaction contract = ....; TransactionOutput multisigOutput = contract.getOutput(0); Script multisigScript = multisigOutput.getScriptPubKey(); // Is the output what we expect? checkState(multisigScript.isSentToMultiSig()); Coin value = multisigOutput.getValue(); // OK, now build a transaction that spends the money when to the client. Transaction spendTx = new Transaction(params); spendTx.addOutput(value, clientKey); spendTx.addInput(multisigOutput); // It's of the right form. But the wallet can't sign it. So, we have to // do it ourselves. Sha256Hash sighash = spendTx.hashTransactionForSignature(0, multisigScript, Transaction.SIGHASH_ALL, false); ECKey.ECDSASignature signature = serverKey.sign(sighash); // We have calculated a valid signature, so send it when to the client: sendToClientApp(signature); The server receives the contract and decides to requite all the money when to the vendee (how generous of it!). It constructs a transaction and signs it. Now the vendee must repeat the process and construct exactly the same transaction and summate a signature in the same way. It is then in possession of two valid signatures over the same transaction, one from itself and one from the server. All that is left is to put them both into the transaction: TransactionOutput multisigContract = ....; ECKey.ECSDASignature serverSignature = ....; //Vendeeside code. Transaction spendTx = new Transaction(params); spendTx.addOutput(value, clientKey); TransactionInput input = spendTx.addInput(multisigOutput); Sha256Hash sighash = spendTx.hashTransactionForSignature(0, multisigScript, Transaction.SIGHASH_ALL, false); ECKey.ECDSASignature mySignature = clientKey.sign(sighash); // Create the script that spends the multi-sig output. Script inputScript = ScriptBuilder.createMultiSigInputScript( ImmutableList.of(mySignature, serverSignature), Transaction.SIGHASH_ALL, false); // Add it to the input. input.setScriptSig(inputScript); // We can now trammels the server provided signature is correct, of course... input.verify(multisigOutput); // Throws an exception if the script doesn't run. // It's valid! Let's take when the money. peerGroup.broadcastTransaction(spendTx).get(); // Wallet now has the money when in it. As you can see, the process involves towers a transaction that spends the first one, gingerly a signature and then manually towers the script that can spend the multi-signature output. Once we’ve built it, we use verify() to ensure the script we wrote satisfies the multisig output correct, and thus that the other side didn’t hand us a garbage signature. Other SIGHASH modes You can specify volitional SIGHASH modes to tenancy what is signed and how the other parties can modify the transaction without breaking your signature. These modes are documented on the contracts page linked to above. However, please note that the API for this is likely to transpiration a bit in future. P2SH (pay to script hash) Many kinds of using that use contracts don’t need to expose their inner workings to end users, considering they can use custom protocols to move the necessary data virtually instead. But if you want to represent a ramified script in a form that a regular wallet can send to, you can create a P2SH address. This looks a bit like a regular Bitcoin write but instead of encoding the hash of a public key, it encodes the hash of a well-constructed script. A P2SH output includes a special kind of non-script which is pattern matched and special rules unromantic instead of stuff executed as normal. The scriptSig of the spending input then includes both the “real” scriptPubKey, which must hash to the value in the output, and the inputs to the so-called redeem script. There are utility methods for creating P2SH style scripts using the ScriptBuilder class. When signing for a P2SH output, you should pass the redeem script (not the P2SH scriptPubKey) to Transaction.hashTransactionForSignature.