2181f4859d
<http://opentransactions.org/wiki/index.php/Voting_Pool_Withdrawal_Process> Also includes some refactorings and other improvements, including better docs and a new error type (votingpool.Error) used for all votingpool-specific errors.
99 lines
4.4 KiB
Go
99 lines
4.4 KiB
Go
/*
|
|
* Copyright (c) 2014 Conformal Systems LLC <info@conformal.com>
|
|
*
|
|
* Permission to use, copy, modify, and distribute this software for any
|
|
* purpose with or without fee is hereby granted, provided that the above
|
|
* copyright notice and this permission notice appear in all copies.
|
|
*
|
|
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
*/
|
|
|
|
/*
|
|
Package votingpool provides voting pool functionality for btcwallet.
|
|
|
|
Overview
|
|
|
|
The purpose of the voting pool package is to make it possible to store
|
|
bitcoins using m-of-n multisig transactions. A pool can have multiple
|
|
series, each of them with a set of pubkeys (one for each of the members
|
|
in that pool's series) and the minimum number of required signatures (m)
|
|
needed to spend the pool's coins. Each member will hold a private key
|
|
matching one of the series' public keys, and at least m members will
|
|
need to be in agreement when spending the pool's coins.
|
|
|
|
More details about voting pools as well as some of its use cases can
|
|
be found at http://opentransactions.org/wiki/index.php?title=Category:Voting_Pools
|
|
|
|
This package depends on the waddrmgr and walletdb packages.
|
|
|
|
Creating a voting pool
|
|
|
|
A voting pool is created via the Create function. This function
|
|
accepts a database namespace which will be used to store all
|
|
information related to that pool under a bucket whose key is the
|
|
pool's ID.
|
|
|
|
Loading an existing pool
|
|
|
|
An existing voting pool is loaded via the Load function, which accepts
|
|
the database name used when creating the pool as well as the poolID.
|
|
|
|
Creating a series
|
|
|
|
A series can be created via the CreateSeries method, which accepts a
|
|
version number, a series identifier, a number of required signatures
|
|
(m in m-of-n multisig), and a set of public keys.
|
|
|
|
Deposit Addresses
|
|
|
|
A deposit address can be created via the DepositScriptAddress
|
|
method, which returns a series-specific P2SH address from the multi-sig
|
|
script constructed with the index-th child of the series' public keys and
|
|
sorted according to the given branch. The procedure to construct multi-sig
|
|
deposit addresses is described in detail at
|
|
http://opentransactions.org/wiki/index.php/Deposit_Address_(voting_pools)
|
|
|
|
Replacing a series
|
|
|
|
A series can be replaced via the ReplaceSeries method. It accepts
|
|
the same parameters as the CreateSeries method.
|
|
|
|
Empowering a series
|
|
|
|
For security reasons, most private keys will be maintained offline and
|
|
only brought online when they're needed. In order to bring a key online,
|
|
one must use the EmpowerSeries method, which takes just the series ID
|
|
and a raw private key matching one of the series' public keys.
|
|
|
|
Starting withdrawals
|
|
|
|
When withdrawing coins from the pool, we employ a deterministic process
|
|
in order to minimise the cost of coordinating transaction signing. For
|
|
this to work, members of the pool have to perform an out-of-band consensus
|
|
process (<http://opentransactions.org/wiki/index.php/Consensus_Process_(voting_pools)>)
|
|
to define the following parameters, that should be passed to the
|
|
StartWithdrawal method:
|
|
|
|
roundID: the unique identifier of a given consensus round
|
|
requests: a list with outputs requested by users of the voting pool
|
|
startAddress: the seriesID, branch and indes where we should start looking for inputs
|
|
lastSeriesID: the ID of the last series where we should take inputs from
|
|
changeStart: the first change address to use
|
|
dustThreshold: the minimum amount of satoshis an input needs to be considered eligible
|
|
|
|
StartWithdrawal will then select all eligible inputs in the given address
|
|
range (following the algorithim at <http://opentransactions.org/wiki/index.php/Input_Selection_Algorithm_(voting_pools)>)
|
|
and use them to construct transactions (<http://opentransactions.org/wiki/index.php/Category:Transaction_Construction_Algorithm_(voting_pools)>)
|
|
that fulfill the output requests. It returns a WithdrawalStatus containing
|
|
the state of every requested output, the raw signatures for the constructed
|
|
transactions, the network fees included in those transactions and the input
|
|
range to use in the next withdrawal.
|
|
|
|
*/
|
|
package votingpool
|