tx_submission.md

Current Transaction Submission State Machine

The reason for this migration is to make the TransactionError available in the Rejected state. While we are at it we remove the operation state wrapper as operation ids will in the future be tracked outside of the state machines and this is the only place where its used anyways. Furthermore, we make the transaction available in all states in case we need it in the future and remove the deprectaed NonRetryableError state.

OperationState<TxSubmissionStates> {
    operation_id: OperationId,
    state: TxSubmissionStates,
}

pub enum TxSubmissionStates {
    /// The transaction has been created and potentially already been submitted,
    /// but no rejection or acceptance happened so far
    Created(Transaction),
    /// The transaction has been accepted in consensus
    ///
    /// **This state is final**
    Accepted(TransactionId),
    /// The transaction has been rejected by a quorum on submission
    ///
    /// **This state is final**
    Rejected(TransactionId, String),
    #[deprecated(since = "0.2.2", note = "all errors should be retried")]
    NonRetryableError(String),
}

Migration Goal

SubmissionStateMachine {
    common: Common,
    state: TxSubmissionSMState,
}

Common {
    operation_id: OperationId,
    transaction: Transaction,
}

pub enum SubmissionSMState {
    /// The transaction has been created and potentially already been submitted,
    /// but no rejection or acceptance happened so far
    Created,
    /// The transaction has been accepted in consensus
    ///
    /// **This state is final**
    Accepted,
    /// The transaction has been rejected by a quorum on submission
    ///
    /// **This state is final**
    Rejected(TransactionError),
}

Current Mint Output State Machine

pub enum MintOutputStates {
    /// Issuance request was created, we are waiting for blind signatures
    Created(Amount, NoteIssuanceRequest),
    /// The transaction containing the issuance was rejected, we can stop
    /// looking for decryption shares
    Aborted,
    // FIXME: handle offline federation failure mode more gracefully
    /// The transaction containing the issuance was accepted but an unexpected
    /// error occurred, this should never happen with a honest federation and
    /// bug-free code.
    Failed(String),
    /// The issuance was completed successfully and the e-cash notes added to
    /// our wallet
    Succeeded(Amount),
}

pub struct MintOutputCommon {
    operation_id: OperationId,
    out_point: OutPoint,
}

pub struct MintOutputStateMachine {
    common: MintOutputCommon,
    state: MintOutputStates,
}

Migration Goal

The reason for this migration is to make the TransactionError available in the Aborted state. While we are at it we pull out the amount and save the resulting note in the final state in case we need it at some point.

pub enum MintOutputSMState {
    /// Issuance request was created, we are waiting for blind signatures
    Created(NoteIssuanceRequest),
    /// The transaction containing the issuance was rejected, we can stop
    /// looking for decryption shares
    Aborted(TransactionError),
    /// The transaction containing the issuance was accepted but an unexpected
    /// error occurred, this should never happen with a honest federation and
    /// bug-free code.
    Failure,
    /// The issuance was completed successfully and the e-cash notes added to
    /// our wallet
    Success(Note),
}

pub struct Common {
    operation_id: OperationId,
    out_point: OutPoint,
    amount: Amount,
}

pub struct MintOutputStateMachine {
    common: Common,
    state: MintOutputSMState,
}