Skip to main content

Introduction

This page describes how Cowboy ensures that a submitted transaction is applied at most once, and how protocol-driven message execution avoids duplicate state transitions. The description follows the Cowboy whitepaper and CIPs.
Idempotency on Cowboy is achieved via per-account nonces and a single canonical block order; protocol-delivered messages (timers, deferred callbacks) are serialized by consensus.

Definition and Scope

  • Idempotency refers to the guarantee that a transaction, once accepted and executed, cannot be executed again to produce additional state transitions.
  • The scope includes: user-submitted transactions, protocol-delivered timer messages (CIP-5), and deferred callbacks produced by the off-chain compute framework (CIP‑2).

Mechanisms

Account Nonce and Transaction Validation (Whitepaper)

  • The global state tracks per-address account data, including nonce (whitepaper: state contains balance and nonce).
  • During block processing, the state transition function validates each transaction’s signature, nonce, and balance before execution (whitepaper: “Validate signature, nonce, and balance.”).
  • Consequences for idempotency:
    • A replay of the same signed transaction is rejected once the sender’s nonce has advanced.
    • Out-of-order transactions are not executed until the correct nonce is present.

Deterministic Ordering and Single Inclusion (Whitepaper)

  • Cowboy employs a Simplex-based BFT protocol to produce a single canonical ordering of blocks. Within this ordering, nonce checks ensure that a user transaction can be accepted and executed at most once.

Timers and the Actor Scheduler (CIP-5)

  • The CIP-5 scheduler selects a bounded window from the oldest due height, preserving FIFO insertion order within that height. A complete resource request that cannot fit carries forward under the bounded carry/dead-letter rules. Expired or insufficiently funded timers are removed under the independent cleanup budget; bids do not affect admission.
  • Each admitted timer consumes its reserved authority once in that block. CIP-5 then applies its removal, failure-retry, or native re-arm rule. Deferral does not duplicate the selected record or promise execution before expiry or carry limits.

Deferred Transactions for Off‑chain Callbacks (CIP‑2)

  • After collecting the required number of results for an off‑chain task, the Result Verifier constructs and signs a deferred transaction containing the developer-specified callback. Validators include and execute this deferred transaction in a future block.
  • The chain pays the runners from the job’s escrow when it verifies the result, so the callback has nothing to settle and a result can’t be paid twice.

Practical Notes

  • User-submitted transactions rely on signature and nonce validation for replay protection and single execution.
  • Protocol-delivered messages (timers and deferred callbacks) are scheduled, included, and executed by consensus rules. When not executed, they are carried forward by protocol logic rather than duplicated within the same block.

Further Reading