Builders Guide
Application Development
Transactions
Transaction Statuses

Transaction Statuses on GOAT Network

⚠️

This guide is based on Testnet3. Status definitions and behavior may be adjusted for mainnet deployment.

Understanding transaction statuses on the GOAT Network is essential for tracking progress and handling transactions effectively in your applications.

Transaction Lifecycle

Transactions on the GOAT Network pass through several distinct stages before achieving finality on the Bitcoin blockchain. Each stage provides different levels of security and feedback for users.

1. Pending

  • Description:
    • The transaction has been submitted to the network but is not yet included in a block.
  • Availability:
    • Query the pending transaction pool using eth_getTransactionByHash.
  • Characteristics:
    • Transaction can still be replaced or canceled by resubmitting with the same nonce and higher gas fees.
  • Developer Note:
    • Display as "Pending" in the UI, with an option for users to replace or cancel the transaction.

2. Sequencer Confirmed (Unsafe - pending publication)

  • Description:
    • The transaction has been included in a block by the Sequencer on the GOAT Network.
    • This block has not yet been published to the Bitcoin blockchain.
  • Timeframe: Usually 2-4 seconds.
  • Characteristics:
    • Provides rapid feedback to users.
    • Not secured by Bitcoin’s proof-of-work.
  • Developer Note:
    • Label this as "Sequencer Confirmed" or "Pending Confirmation" in your application.
    • Advise users to wait for publication to Bitcoin for stronger security guarantees.

3. Published to Bitcoin (Safe)

  • Description:
    • The Sequencer block containing the transaction has been published to the Bitcoin blockchain.
  • Timeframe: Typically 10-60 minutes, depending on Bitcoin block times.
  • Characteristics:
    • Gains security from Bitcoin’s blockchain but may still be affected by reorgs.
    • Finality is pending until sufficient confirmations are achieved.
  • Developer Note:
    • Display as "Published" or "Confirmed (Pending Finality)."
    • Inform users about the current confirmation count and expected finality timeframe.

4. Finalized

  • Description:
    • The transaction has achieved finality on the Bitcoin blockchain after receiving the required number of confirmations.
  • Timeframe: Varies based on the number of confirmations (e.g., ~6 confirmations for ~1 hour).
  • Characteristics:
    • Immutable and fully secured by Bitcoin’s proof-of-work.
  • Developer Note:
    • Display as "Finalized" or "Completed."
    • Indicate that the transaction is now permanent and irreversible.

Special Considerations

Reorgs and Forks

  • Explanation:
    • Bitcoin blockchain reorganizations (reorgs) can affect transactions in the "Published to Bitcoin" state.
  • Impact:
    • Transactions may be reversed if included in orphaned blocks.
  • Mitigation:
    • Wait for sufficient confirmations (e.g., 6+) before treating a transaction as final.

Transaction Failures

  • Potential Causes:
    • Insufficient Gas or Fees: Transaction rejected due to low gas price or insufficient gas limit.
    • Smart Contract Errors: Execution errors caused by invalid inputs or logic.
  • Handling Failures:
    • Monitor the transaction receipt for status: false.
    • Inform users of failure reasons and provide actionable steps to resolve issues (e.g., resubmitting with higher fees).

Batch Transactions with EIP-1559

  • Atomicity:
    • All operations within a batch are executed atomically. If one operation fails, the entire batch is reverted.
  • Status Application:
    • The transaction status applies uniformly to the entire batch.
  • Developer Note:
    • Ensure error handling accounts for full batch reverts when working with EIP-1559 batch operations.

Monitoring Transaction Statuses

Event Listeners

  • Set up event listeners in your application to track transaction hashes and status updates in real-time.

RPC Methods

  • Utilize the following RPC methods to monitor transactions:
    • eth_getTransactionReceipt: Retrieve the transaction status and related information.
    • eth_getBlockByNumber: Check the inclusion of transactions in blocks.

Block Explorer

Best Practices for Developers

  1. Communicate Status Clearly:

    • Provide users with clear, descriptive statuses at each stage of the transaction lifecycle.
    • Include contextual information, such as estimated timeframes and security implications.

  2. Implement Timeouts and Retries:

    • Set timeouts for pending transactions and allow users to retry if necessary.
    • Use retries cautiously to prevent nonce conflicts.

  3. Handle Reorgs Gracefully:

    • Account for possible reorgs by monitoring confirmations and updating transaction states accordingly.

  4. Test Extensively:

    • Simulate various transaction states and edge cases (e.g., failures, reorgs) on Testnet3 to validate application behavior.

  5. Stay Synchronized:

    • Regularly poll the network for updates to keep your application state consistent with the blockchain.

Additional Resources

Fee EstimationOverview