Introduction

In order to avoid an expensive and error-prone consensus process, it is mandatory for wallets to be able to construct withdrawal transactions in a deterministic manner, assuming they are given the withdrawal requests in a deterministic order. Once this is accomplished, then it only becomes necessary for wallets to share signatures among themselves because they know they all signed the exact same bitcoin transaction.

Procedure

Overview

iframe

Initial Conditions

The startwithdrawal API call has been received by the wallet, and all the arguments have been checked for errors.

Sequence

The basic flow of the procedure is:

Gather accounting information from the API call arguments

Validate and sort the output list

Start a new transactions

Add outputs to the transaction until either all outputs are added or all inputs are used.

Make sure all generated transactions are ready for signing.

Create a list of all signatures which the wallet is capable of generating.

Create a status list containing the deposition of every output the caller specified.

Return the status list and signature list to the caller.

Each step in this chart is more fully described below.

Preparation

iframe

Initial Conditions

The startwithdrawal API call has been received by the wallet, and all the arguments have been checked for errors.

Sequence

The algorithm must keep track of the next change address to be used. The initial value is supplied as the changestart argument. Any time a change output is allocated, the index value of the address identifier is incremented, and if a change output is remove from a transaction the index value is decremented. The final value will be returned to the caller as the nextchangestart value in the withdrawal status list.

Prepare an empty list for holding transactions as they are constructed and before they are signed.

Prepare an empty array to hold the transaction signatures which will be returned to the caller as the signatures value.

Prepare an withdrawal status object.

roundID: copied from roundID argument

nextinputstart: nil

nextchangestart: nil

fees: 0

outputs: should contain an entry for every output passed:

outBailmentID: copied from outBailmentID entry in outputs argument

status: empty string

transactions: nil

Output List Initialization

iframe

Initial Conditions

The startwithdrawal API call has been received by the wallet, and all the arguments have been checked for errors.

Sequence

Pass the inputstart, inputstop, and dustthreshold parameters to the input selection algorithm to obtain an ordered list of eligible inputs.

Perform a first pass check to determine if the requested outputs exceed the size of the eligible inputs. Note that this check is only definitive in the case where the output sum is greater than the input sum. At this stage of the algorithm, the input sum exceeding the output sum does not prove that all outputs will be successfully created.

Take the sum of both lists.

If the sum of the outputs exceeds the sum of the inputs, remove outputs in descending size order until this is no longer true. Note this may result in the output list being an empty set.

If the output list is non-empty, sort it by outBailmentID

Move both the input lists and outputs lists into separate stacks by pushing them in reverse list order. The first input and first output should be on the top of their respective stacks.

Initialize New Transaction

iframe

Initial Conditions

There are no pending transactions to in the process of being constructed, either because this is the first transaction of the algorithm or because a previous pending transaction has been moved to the finished transaction list.

The input stack contains at least one input.

The output stack contains at least one output.

Sequence

Create a minimal transaction skeleton with a header and one change output.

The change output will be the last output of the transaction, but the number of other outputs in this transaction is not yet known.

The change output must be included in the skeleton for transaction size calculations.

The position index for the change output is nil.

The first non-change output for the transaction will be placed at position index 0.

After creating the transaction skeleton, and after any action which alters it, the new transaction size (bytes) and minimum required transaction fee must be recalculated.

Add Next Output

iframe

Initial Conditions

The output stack contains at least one output.

There is a transaction in progress which is ready to accept new outputs. This transaction is either empty or it contains 1 or more outputs.

If the transaction already contains outputs, then it also contains sufficient inputs to cover those outputs and any required transaction fees without exceeding size limits. This is because it must have already successfully passed through this procedure before.

Sequence

Locate the entry for this output in the withdrawal status object by finding the corresponding outBailmentID.

Validate the output address.

If it is invalid, update status entry for this output to "invalid" and exit from this procedure.

Loop through every (non-change) output in the transaction and update the withdrawal status object for the corresponding output.

The withdrawal status object contain an entry for every output in the transaction, where each entry has an transactions object containing a nil ntxid, an index matching the output position index, and a matching amount.

Update the nxid value from nil to the ntxid for the transaction.

Add the fees from this transaction to the fees property of the withdrawal status object.

Move the transaction to the finished transaction list.

Update Signatures

iframe

Initial Conditions

The finished transaction list contains zero or more finalized transactions

The transactions are valid in all respects except for missing signatures

Sequence

If the finished transaction list is empty, the rest of the procedure can be skipped.

Update Status

Initial Conditions

Sequence

Split outBailments have more than one item in their transactions array and have an existing status value of "success".

Change the status for all split outBailments from "success" to "split".

Update the status for any partial outBailments which exist:

Partial outBailments have existing status value of "partial-".

Calculate the total missing value needed to satisfy the partial outputs.

The missing value of an outBailment is the originally-requested size of the outBailment minus the sum of all outputs created to satisfy it (if any exist).

Obtain a list of eligible inputs from the next un-thawed series and calculate their total value.

If the eligible value of the next un-thawed series is greater than the total missing value, then the next un-thawed series is the target series.

If not, repeat the above process while keeping a running total of eligible value until a target series is located.

Append the number of the target series to the status value for every partial series.

Update the nextinputstart value.

If the input stack is empty, nextinputstart is the first address identifier for the next un-thawed series.

If the input stack is not empty, nextinputstart is the address identifier for the next input in the stack.

Oversize Transaction

iframe

An oversize transaction may occur while attempting to add inputs to satisfy an output which has been added to a transaction as part of the Add Next Output step.

Even with the worst case of high m and/or n values, inputs will never be large enough that a transaction can be oversized while attempting to add the first input to a transaction.

Oversize transactions will have one change output, at least one non-change output, and many inputs.

If an oversize has two or more non-change outputs, then Add Next Output was successful for the previous output. In this case, the transaction was valid before attempting to add the current output, so the current output should be removed from the current transaction and moved to the next one.

Otherwise, the transaction has become too large while adding its first non-change output. This can happen due to a series of small inputs, or a large output, or a combination of the two. In this case the outBailment can not be satisfied with a single transaction and must be split across multiple transactions.

Initial Conditions

The Add Next Output procedure has created a transaction that exceeds size limits, in one of the following circumstances:

Immediately upon adding an output to the transaction

The transaction contains other outputs which were added successfully. All inputs currently in the transaction are required to satisfy the previous output(s) before the output that failed.

After adding the first input to the transaction to satisfy an output

The transaction contains other outputs which were added successfully. All inputs currently in the transaction are required to satisfy the previous output(s) before the output that failed.

After having added at least one input to the transaction to satisfy an output without causing an oversize condition.

At least one of the inputs in this transaction are only required to satisfy the current output, not any previous outputs (if any exist).

Procedure

Rollback Last Output

iframe

This procedure is used if a transaction has exceeded the size limit, and can be brought back under the limit by removing the most-recently added output and the inputs needed to support it from the transaction

The removed inputs and outputs will be added to the beginning of a new transaction.

This procedure will remove one more input than is required to bring the transaction below size limits, and then add exactly one more. This will always result in a valid transaction because the only way to reach this procedure is by having successfully completed at least one Add Next Output cycle for the current transaction prior to adding an output or input that pushes the transaction over the size limit.

Initial Conditions

An oversize transaction contains one or more outputs and their supporting inputs which do not exceed transaction size limits, and one output which does not.

The number of inputs which are solely dedicated to satisfying the most recently-added output (not required for previous outputs) may be zero or more.

Sequence

Remove the most-recently added output from the transaction and return it to the output stack.

This will cause the output to be the first one added to the next transaction.

Remove the most-recently added input from the transaction and return it to the input stack.

If the sum of input values exceeds the sum of output values by an amount greater than the required transaction fee:

Continue removing inputs one at a time until the sum of the input values falls below the needed output + transaction fee value.

Insufficient Inputs

This procedure is followed when the Output List Initialization step estimated that that the input list was sufficient to fulfill the valid outputs but, due to change and/or transaction fees, one or more outputs can not be fulfilled.

Initial Conditions

At least one output remains in the stack, but the input stack is empty.

Sequence

Pop all outputs from the output stack and update their status property in the withdrawal status list to "partial-".

No further action is necessary. After completing this procedure the algorithm moves on to the Finalize Transaction procedure which will discard the empty transaction skeleton which would have otherwise contained the outputs which were processed in this procedure.