Voting Pool Deposit Process
Contents
Procedure
Initiation
Customers will normally request a deposit address by interacting with the service front end web site or some other software application. When the service receives such a request, it notifies the OT client via the OT client API function: request_bailment
.
When the OT client receives notice of a user desire to deposit funds to a voting pool, via any method, it sends a bailment
transaction request to the notary to initiate the deposit process.
The notary validates this request, and replies with a signed receipt. A copy of this receipt is broadcasted to the audit stream
, and another copy is stored inside an initiatedBailment
notice that’s placed in the user’s inbox. The notary adds this association to a bailment database for future reference.
Payment script generation
When an audit server validates the notary’s reply to the bailment
message from the notary to which it is assigned, it adds the receipt identifier to its bailment database
and calls getdepositscript
via the websocket interface to the blockchain wallet, using the address identifier for the next unused deposit address.
The wallet calculates and returns the designated deposit address as P2SH output script. The audit server uses this information to update the bailment database, and to assemble and sign a PaymentRequest
.
PaymentRequest delivery
The audit server broadcasts the PaymentRequest
to all notaryies and auditors in the pool. The notary replaces the user’s initiatedBailment
notice in the inbox with a pendingBailment
notice containing a copy of the PaymentRequest
.
When the other audit servers in the pool receive the PaymentRequest
broadcast they add the deposit to their respective bailment databases. The other notaries in the pool cache the PaymentRequest
to answer verification requests from the OT client.
The OT client should validate the PaymentRequest
against the voting pool asset contract. If it is valid then it should query a random selection of other notaries, at least m-1
, using the PaymentRequest identifier
to verify whether they have seen it. If this check is successful, it then initiates the blockchain transaction by passing the PaymentRequest
to the user's local wallet application which is configured to handle [[bitcoin:]] URIs
.
Deposit and crediting
- Type 1 Event - Fraudulent Deposit Address
- A malicious or hacked operator may give the customer an invalid
PaymentRequest
in an attempt to steal deposits.
Each pool member’s Bitcoin wallet must notify its audit server of any deposits received to an address which the pool controls. When an incoming transaction is received to an address the audit servers are expecting due to previously broadcast PaymentRequest
, they will use the getinfomultisigwalletaddress
calls to identify the incoming transaction, and gettransactionstatus
to monitor its confirmation status.
- Type 0 Event - Deposit Never Received
- It’s possible that the customer may never actually transfer bitcoins after requesting a PaymentRequest.
- Type 1 Event - Unknown Deposit
- A deposit may be received to an address which has never been used, and for which a PaymentRequest was never created so no member of the pool knows to which nym it should be credited.
- Type 1 Event - Duplicate Deposit
- A deposit may be received from an address which has been previously used, so the audit servers know to which nym the address is assigned.
- Type 0 Event - Dust Handling
The size of the deposit may be below the network dust threshold (small enough that it would require more in transaction fees to spend than it is worth).
The audit server relays the number of confirmations the incoming transaction has received to the notary. Once the number is sufficient according to the Funds Available Policy the notary will issue an OT asset for the amount of the deposit to the nym of the user.
The notary will replace the pendingBailment
notice (in the inbox) with a completedBailment
notice, which includes a signed copy of the original bailment
request, as well as a copy of the audit server’s signed notice of confirmations, which includes the transaction identifier provided by the blockchain wallet.
The OT client processes the user’s OT account inbox, removing the completedBailment
notice, which simultaneously closes the transaction number and updates his OT balance.
The audit servers in the pool must monitor all deposits to ensure the Funds Available Policy is satisfied to avoid the risk of a double spend or chain fork causing insolvency. Any server which offers more early deposit credits than what it can cover with its service account must have its audit status set to degraded
.
- Type 2 Event - Non-credited Deposit
- The notary fails to place a
completedBailment
notice in the user’s inbox after a successful Bitcoin transfer.
If an initially-seen deposit fails due to a chain fork, and if the user has not yet been credited with an OT receipt for the deposit, the status of the deposit remains pending. The audit server should notify the notary by setting the number of confirmations back to zero. In the typical case of blockchain reorg event, the deposit transaction should re-enter the mempool automatically and the wallet can assist with this by rebroadcasting it.
If an initially-seen deposit has become invalid due to conflicting transactions which made it into the blockchain, the audit server should mark the deposit as failed
by setting the number of confirmations to -1. The audit server should notify the notary of the failure, who then replaces the user’s pendingBailment
notice with a failedBailment
notice. The notary should update the status to failed
in the bailment database and the address should not be intentionally reused. The OT client can then process the user’s inbox, removing the failedBailment
notice and closing the transaction number. In this case there is no change to the OT account balance, unlike with a completeBailment
notice.
- Type 1 Event - Reversed Deposit
- A deposit could disappear from the blockchain after the user has already been issued an OT receipt