Transaction Lifecycle

In Levain, a transaction can go through different statuses as it moves from off-chain approvals and signing to on-chain broadcasting of signed transaction and execution. Generally, transactions are categorized into:

  • Transaction requests, which is typically the off-chain process of getting approvals and signing of a transaction
  • Transaction, which is the actual on-chain transaction

Transaction Request Workflow

stateDiagram-v2 [*] --> PENDING_APPROVALS: Transaction request initiated PENDING_APPROVALS --> APPROVED: All transaction approvals\nreceived, meeting threshold APPROVED --> PENDING_GAS_TANK_SIGNATURE: Transaction co-signed by Signer PENDING_GAS_TANK_SIGNATURE --> SIGNED: Transaction co-signed by Levain SIGNED --> EXECUTED: Transaction broadcast on-chain PENDING_APPROVALS --> REJECTED: Rejected by any\nWallet Approver APPROVED --> REJECTED: Rejected by\nSigner

A typical transaction request workflow is as follows:

  1. A user initiates a transaction request, which begins in the PENDING_APPROVALS status.
  2. The transaction request is sent to Wallet Approvers assigned to that specific wallet, for approval.
  3. Once the transaction request has received enough approvals from the Wallet Approvers, it is sent to the Signer for the actual transaction co-signing, and will be moved to APPROVED status.
  4. Levain sends back the encrypted user signing key to the Signer for client-side decryption.
  5. The Signer decrypts the encrypted user signing key and uses that key to co-sign the transaction, to produce the first signature, and will be moved to PENDING_GAS_TANK_SIGNATURE status.
  6. The co-signed transaction is then sent to Levain for co-signing, to produce the second signature, and will be moved to SIGNED status.
  7. Levain will subsequently broadcast this fully signed transaction (i.e. with two signatures) to the blockchain for execution, and will be moved to EXECUTED status.

Note that while a transaction request requires a threshold number of Wallet Approvers to approve for it to reach the APPROVED status, any rejection by the Signer or any Wallet Approver will result in the transaction request being rejected, and will be moved to REJECTED status.

Now that the transaction request has been approved, fully signed by the user and Levain, and executed on-chain, the transaction request is considered completed.

Transaction Workflow

Next, we will look at the transaction lifecycle.

stateDiagram-v2 [*] --> UNCONFIRMED: Transaction broadcasted on-chain UNCONFIRMED --> CONFIRMED: Transaction confirmed on-chain UNCONFIRMED --> FAILED: Transaction failed on-chain

A typical transaction workflow is as follows:

  1. Once a transaction is broadcast on-chain, it will initially be in the UNCONFIRMED status.
  2. A transaction is considered confirmed once it has been confirmed on-chain, and will be moved to CONFIRMED status, or failed on-chain, and will be moved to FAILED status.

Transactions can fail on-chain for various circumstances:

  • Transaction ran out of gas, due to insufficient gas limit
  • Transaction reverted due to a failed require or assert statement in the smart contract