Sweepprivkey proposal
sweepprivkey is a PROPOSED Bitcoin RPC command that, given a Bitcoin private key, allows sweeping of some or all of the funds to another address. Despite this specification, this proposal has never been implemented, and cannot be considered for inclusion until it is.
This function is useful for merchants who wish to accept typed or scanned Bitcoin private keys as payments, without imposing any specific methodology on how the payments must be processed. sweepprivkey has no direct effect on anything in the local wallet or transaction history -- the function simply generates a transaction in real-time to sweep the funds to another address, and broadcasts it. That destination address may or may not be in the local wallet.
The local wallet is only affected if the destination address is in the wallet, and only in an indirect sense: the wallet reacts to the sudden presence of a new transaction referencing it, just the same as if that transaction had been received from a peer.
This allows merchants to offer a "deposit by private key" method with trivial effort, specifically without having to create a separate deposit implementation for accepting the keys. The merchant can simply expose a way for users to submit private keys, which can then be passed to sweepprivkey with minimal validation along with the same deposit address that the merchant would normally have given to their customer in anticipation of payment.
Once the customer has entered a private key and allowed a sweep to take place, the merchant from its perspective will see what looks like a deposit with zero confirmations, and can treat it exactly the same as a normal deposit from outside (including requiring the customer to wait for confirmations as usual, where applicable).
Usage
The syntax of sweepprivkey is as follows:
sweepprivkey <privkey> <minconfirms> [<destinationtype> <destination>] [<fee>] [<amount> <changeaddress>]
- privkey is required. It can be in any private key format normally accepted for wallet imports with the importprivkey function.
- minconfirms determines how many confirmations the private key's prior transactions must have before they are considered eligible for being swept. Transactions having less than the minimum confirmations will be ignored. If this is 0, then sweepprivkey will also attempt to sweep unconfirmed transactions from the in-memory pool.
- destinationtype is either the word "address" or "account", and indicates what destination is. "address" means sweep funds to another Bitcoin address, and "account" will perform a getnewaddress operation to get an address on the local wallet and sweep the funds there. destinationtype and destination are optional, but must both be present together when used. If these are absent, the command is treated as a simple query which returns the total funds available to the private key.
- destination is either a Bitcoin address (if destinationtype is "address"), or is an account name (if destinationtype is "account"). Funds are sent here.
- fee is optional, but must be provided if amount is provided (so that the command knows which parameter is which). This determines how much of a transaction fee to pay. This can be either an amount, or the word "default", or the word "minimum". Default means to pay the transaction fee configured in the bitcoin client, and is the choice assumed if omitted. Minimum means to pay the minimum fee that the client believes will be required to ensure that the transaction is relayed by the network (which is based on the transaction's age, size, and other factors - see GetMinFee). In many cases, the fee may be zero. If you specify an amount but it is below the minimum, or the private key doesn't have a balance large enough to meet the minimum, the command reports failure. Fees are always paid from the funds held by the swept private key, not the wallet.
- amount and changeaddress are optional. When not present, the command will attempt to sweep all funds available via the private key to the extent those funds have enough confirmations to satisfy minconfirms. If an amount is present, the command will only sweep that amount, reporting a failure if amount (plus fee) is greater than the funds available. If the private key contains funds that satisfy minconfirms as well as funds that do not, only the sufficiently confirmed funds are swept. If a specific amount is requested and a transaction fee must be paid, it will be deducted out of the change rather than the requested transfer amount (FIXME: this seems irrational). changeaddress address specifies a destination for any leftover change that may be the result of sweeping a partial amount. Not all partial-balance transactions will generate change, particularly if the private key's received amount satisfies exactly the sweep amount. If there is no change, the change address is ignored.
Proposed flowchart
The sweepprivkey function depends on the ability to quickly find transactions in the UTXO set controlled by a given private key; simply, a UTXO index on scriptPubKey.
When the sweepprivkey command is run, bitcoind will:
- Ensure the necessary UTXO index is being maintained. If not, it will be built before continuing.
- Find the UTXO which is assigned to a standard scriptPubKey redeemable with only the given private key, and ensure it is buried under enough blocks to satisfy the desired level of minconfirms.
- Confirm that, if amount is specified, the amount received is equal to or greater than it.
- Do getnewaddress if a wallet account was specified.
- Construct a new transaction in memory that spends funds from the found UTXO to the destination address and, if necessary, the change address. Sign the transaction with privkey.
- Treat the signed transaction the same as if it had come from a peer, including relaying it to all connected peers.
- Return success with the txid and (if applicable) the new address that was gathered via getnewaddress.