Raw Transaction RPC calls

[Gavin Andresen]

Cross-posting from the bitcoin-development list:

I submitted a pull request yesterday that implements low-level "raw" transaction, and am looking for feedback on the API and help with trying to test/break it.

Design doc:  https://gist.github.com/2839617
Pull request: https://github.com/bitcoin/bitcoin/pull/1456
Test plan: https://secure.bettermeans.com/projects/4180/wiki/Raw_Transaction_RPC_Test_Plan

Playing around with this API on the command line I'm pretty happy with the level of abstraction and the way it interacts with existing RPC commands; for example, "createrawtx" is just like "sendmany" in the way outputs are specified.

The signrawtx method is the key new method; it takes a raw transaction, signs as many inputs as it can, and returns the same raw transaction with signatures. Typical usage would be:

Funds are sitting in a multisignature transaction output, and it is time to gather signatures and spend them.

Assumption: you know the multisignature transaction's [txid, outputNumber, amount].

Create a raw transaction to spend, using createrawtx.
Use signrawtx to add your signatures (after unlocking the wallet, if necessary).
Give the transaction to the other person(s) to sign.
You or they submit the transaction to the network using sendrawtx.
I don't imagine anybody but very-early-adopters or ultra-geeks will do this by calling these RPC methods at a command-line. They are really intended for people writing services on top of bitcoind. The service should be careful to include an appropriate transaction fee, or the sendrawtx method is likely to fail.

I've been asked a couple of times: why doesn't signrawtx handle the BIP 0010 (https://en.bitcoin.it/wiki/BIP_0010) transaction format?

I considered parsing/writing BIP 10 format for raw transactions, but decided that reading/writing BIP 10 format should happen at a higher level and not in the low-level RPC calls. So 'raw transactions' are simply hex-encoded into JSON strings, and encoding/decoding them is just a couple of lines of already-written-and-debugged code.

------

Here is the help output and example use for all the new RPC calls:

listunspent [minconf=1] [maxconf=999999]
Returns array of unspent transaction outputs
with between minconf and maxconf (inclusive) confirmations.
Returns an array of 4-element arrays, each of which is:
[transaction id, output, amount, confirmations]

E.g:  listunspent 1 2
Returns:
[
    [
        "2881b33a8c0bbdb45b0a65b36aa6611a05201e316ea3ad718762d48ef9588fb3",
        0,
        40.00000000,
        2
    ],
    [
        "894a0fc535c7b49f434ceb633d8555ea24c8f9775144efb42da85b853280bcd7",
        0,
        50.00000000,
        1
    ]
]

getrawtx <txid>
Returns hexadecimal-encoded, serialized transaction data
for <txid>. Returns an error if <txid> is unknown.

E.g.: getrawtx fce46ea2448820f7bb8091b5f5e3fd75b7b267e60b9a22af88a9eeabfb084233
Returns:
01000000016d40da062b6a0edcaf643b6e25b943baf103941589d287e39d6f425d84ae8b1c00000 0004847304402203fb648ff8381d8961e66ef61ab88afe52826a5179b8a7312742c8d93785ca563 02204240ea12de1211fffab49686f13ca0e78011d1985765be6e6aa8e747852f897d01ffffffff0 100f2052a0100000017a914f96e358e80e8b3660256b211a23ce3377d2f9cb18700000000


createrawtx [["txid",n],...] {address:amount,...}
Create a transaction spending given inputs
(array of (hex transaction id, output number) pairs),
sending to given address(es).
Returns the same information as gettransaction, plus an
extra "rawtx" key with the hex-encoded transaction.
Note that the transaction's inputs are not signed, and
it is not stored in the wallet or transmitted to the network.

E.g.: createrawtx '[ ["fce46ea2448820f7bb8091b5f5e3fd75b7b267e60b9a22af88a9eeabfb084233",0] ]' '{"mqYmZSQQuAWNQcdwBrDwmtTXg2TLNz748L":50}'
Returns:
{
    "version" : 1,
    "locktime" : 0,
    "size" : 85,
    "vin" : [
        {
            "prevout" : {
                "hash" : "fce46ea2448820f7bb8091b5f5e3fd75b7b267e60b9a22af88a9eeabfb084233",
                "n" : 0
            },
            "scriptSig" : "",
            "sequence" : 4294967295
        }
    ],
    "vout" : [
        {
            "value" : 50.00000000,
            "scriptPubKey" : "OP_DUP OP_HASH160 6e0920fc26383dc7e6101bc417cf87169d0cedbd OP_EQUALVERIFY OP_CHECKSIG"
        }
    ],
    "rawtx" : "0100000001334208fbabeea988af229a0be667b2b775fde3f5b59180bbf7208844a26ee4fc00000 00000ffffffff0100f2052a010000001976a9146e0920fc26383dc7e6101bc417cf87169d0cedbd 88ac00000000"
}

signrawtx <hex string> [<prevtx1>,<prevtx2>...]
Sign inputs for raw transaction (serialized, hex-encoded).
Second argument is an array of raw previous transactions that
this transaction depends on but are not yet in the blockchain.
Returns json object with keys:
  rawtx : raw transaction with signature(s) (hex-encoded string)
  complete : 1 if transaction has a complete set of signature (0 if not)

E.g.: signrawtx "0100000001334208fbabeea988af229a0be667b2b775fde3f5b59180bbf7208844a26ee4fc00000 00000ffffffff0100f2052a010000001976a9146e0920fc26383dc7e6101bc417cf87169d0cedbd 88ac00000000" '["01000000016d40da062b6a0edcaf643b6e25b943baf103941589d287e39d6f425d84ae8b1c00000 0004847304402203fb648ff8381d8961e66ef61ab88afe52826a5179b8a7312742c8d93785ca563 02204240ea12de1211fffab49686f13ca0e78011d1985765be6e6aa8e747852f897d01ffffffff0 100f2052a0100000017a914f96e358e80e8b3660256b211a23ce3377d2f9cb18700000000"]'
Returns:
{
    "rawtx" : "0100000001334208fbabeea988af229a0be667b2b775fde3f5b59180bbf7208844a26ee4fc00000 0009100473044022007f3ba1b8bdc156f2340ef1222eb287c3f5481a8078a8dad43aa09fd289ba1 9002201cc72e97406d546dc918159978dc78aee8215a6418375956665ee44e6eacc115014752210 2894ca6e7a6483d0f8fa6110c77c431035e8d462e3a932255d9dda65e8fada55c2103c556ef01e8 9a07ee9ba61581658fa007bf442232daed8b465c47c278550d3dab52aeffffffff0100f2052a010 000001976a9146e0920fc26383dc7e6101bc417cf87169d0cedbd88ac00000000",
    "complete" : false
}

sendrawtx <hex string>
Submits raw transaction (serialized, hex-encoded) to local node and network.
E.g.: sendrawtx 0100000001334208fbabeea988af229a0be667b2b775fde3f5b59180bbf7208844a26ee4fc00000 0009100473044022007f3ba1b8bdc156f2340ef1222eb287c3f5481a8078a8dad43aa09fd289ba1 9002201cc72e97406d546dc918159978dc78aee8215a6418375956665ee44e6eacc115014752210 2894ca6e7a6483d0f8fa6110c77c431035e8d462e3a932255d9dda65e8fada55c2103c556ef01e8 9a07ee9ba61581658fa007bf442232daed8b465c47c278550d3dab52aeffffffff0100f2052a010 000001976a9146e0920fc26383dc7e6101bc417cf87169d0cedbd88ac00000000
Returns:
error: {"code":-22,"message":"TX rejected"}

(Rejected because it doesn't have all required signatures, if it was accepted it would return the transaction id)

[galambo]

I hope this will lead to the Official Bitcoin Client no longer handling wallets for most users. This way, the problem of key security leaves the hands of the Official client developers.

I think the developers can handle this problem, but it is also a distraction.

Many people have had ideas for external hardware wallets that sign transactions and other schemes. I described one such system to protect a wallet with a Yubikey here. The raw transaction output and sending will help make these more possible, and prevent the development team from becoming bogged down in deciding what type of protection should be included with the Client.

[piotr_n]

Finally - thank you!

I've been waiting for the import/export transaction functionality - or as you named it: sendrawtx/getrawtx.
I keep most of my bitcoins in an offline PC and I had to use my own implementation for this.
But now, when it gets into the official client - I'm happy for that.

And the "listunspent" + "createrawtx" - a brilliant and simple idea. Great stuff!

[piotr_n]

Any ideas when this will get included into the main build?

[Gavin Andresen]

Any ideas when this will get included into the main build?

It was pulled into what will become the 0.7 release a while ago.

Documentation is now on the wiki:  https://en.bitcoin.it/wiki/Raw_Transactions

I decided not to abbreviate "transaction" -- none of the other RPC calls use abbreviations. And the features have been tweaked a little bit.

There are some nice unintended-but-useful things you can do with it-- as documented on the wiki page:

Re-broadcast a transaction
If you want to re-broadcast a transaction right away, you can use the getrawtransaction and sendrawtransaction API calls to do that. As a bash shell-script one-liner it would be:

Code:

sendrawtransaction $(getrawtransaction $TXID)

(note that Bitcoin-Qt/bitcoind automatically re-transmit wallet transactions periodically until they are accepted into a block).

Validate a transaction without broadcasting it
If you have a raw transaction and want to make sure all of it's signatures are correct, you can use the signrawtransaction API call. Pass in the hex-encoded raw transaction, any inputs that bitcoind doesn't yet know about, and an empty array of private keys to use to sign the transaction. Passing an empty array of private keys will prevent signrawtransaction from doing any signing; if it returns "complete":1 then all of the existing signatures are valid and there are no signatures missing.

[Andrew Vorobyov]

You must be careful to include an appropriate transaction fee, or the sendrawtransaction method is likely to fail (either immediately or, worse, the transaction will never confirm).

Can somebody comment on this?

How come transaction will NEVER confirm, if signatures are correct. What we can do if transaction hit this state?

[piotr_n]

You must be careful to include an appropriate transaction fee, or the sendrawtransaction method is likely to fail (either immediately or, worse, the transaction will never confirm).

Can somebody comment on this?

How come transaction will NEVER confirm, if signatures are correct. What we can do if transaction hit this state?

As I understand it, there may be two reasons for that:
1) The nodes (including your own) will not accept/relay such a transaction.
2) The miners will not include it in a block.

If a transaction "hits this state" you can fix it by creating a new transaction (this time with a proper fee), which is spending the same coins again.
Though if such an unconfirmed transaction is already stored in your wallet, it might be a problem.
So it is always worth to keep some old backups - then you can delete such a transaction from the wallet by simply recovering the backup and starting the client with "-rescan" switch.
It is also possible to remove a transaction from an existing wallet file, but it requires some extra tools.

In any case a failed transaction does not mean a lost money, so there is no reason to worry much here.

[piotr_n]

Any ideas when this will get included into the main build?

It was pulled into what will become the 0.7 release a while ago.

I love this new version with a built in console. It's just great.

Thanks guys for making it!