> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.lat/llms.txt
> Use this file to discover all available pages before exploring further.

# DoS Limits & Protection

> Multi-layered defense against denial-of-service attacks

## Introduction

Cowboy implements **defense-in-depth** against DoS attacks through strict resource limits, economic disincentives, and protocol-level protections. Every layer is designed to prevent malicious actors from exhausting network resources.

<Warning>
  **Consensus-Critical**: Many limits are protocol-defined in the CIPs. Implementations must enforce the consensus‑critical limits identically as specified.
  Refer to CIP‑1, CIP‑2, and CIP‑3 for normative rules.
</Warning>

<Tip>
  Cowboy combines dual metering (Cycles/Cells) with a scheduler budget and off-chain result schemas to bound execution and data, aligning DoS protections with CIP-3, CIP-1, and CIP-2.
</Tip>

***

## Resource Limit Overview

| Resource             | Limit                                                          | Source |
| -------------------- | -------------------------------------------------------------- | ------ |
| **Cycles** (compute) | Per‑transaction `cycles_limit` enforced by VM                  | CIP‑3  |
| **Cells** (data)     | Per‑transaction `cells_limit`; bytes charged at I/O boundaries | CIP‑3  |
| **Timer processing** | Per‑block processing budget; best‑effort carryover             | CIP‑1  |

***

## Gas Limits (Cycles & Cells)

### Per-Transaction

* Cycles limit (`cycles_limit`): The VM meters computation at Python bytecode/host-call granularity. If the remaining cycles are insufficient, execution halts with “Out of Cycles.” (CIP‑3)
* Cells limit (`cells_limit`): Bytes are charged at I/O boundaries (intrinsic calldata, storage I/O, /tmp I/O, return data). If the remaining cells are insufficient, execution fails. (CIP‑3)

### Per-Block

* Dual basefee adjustment: Cycles and Cells each have an independently adjusted EIP‑1559‑style basefee with bounded per‑block change and a target utilization. Basefee is burned; tips go to the proposer. (CIP‑3)

***

## Data Metering and Sizes

* Intrinsic calldata: The transaction’s payload is charged in Cells before VM execution begins. (CIP‑3)
* Return data: After a handler returns, the byte size of the return value is charged in Cells. (CIP‑3)
* Large data: Inline storage is limited by practical metering; larger artifacts should be stored off‑chain as content‑addressed blobs referenced on‑chain (whitepaper).

***

## Execution Boundaries

* Single-threaded actor handlers: Each actor processes messages sequentially from its mailbox; intra‑handler reentrancy is prevented by design. (Whitepaper)
* Deterministic async scheduling: The protocol forbids true concurrency; async/await follows a deterministic FIFO schedule. (CIP‑3)

***

## Storage Considerations

* Cell metering: Storage reads/writes charge Cells proportional to bytes read/written via host functions. (CIP‑3)

***

## Message and Timer Processing

* Timer processing: The scheduler executes due timers up to a per‑block processing budget determined by protocol parameters and GBA bids; unexecuted timers roll over (“Best‑Effort Delivery”). (CIP‑1)

***

## Network-Level Protections

* Dual basefee: Increases cost during congestion, pricing out low‑value spam and smoothing demand. (CIP‑3)

***

## Economic Protections

* Dual EIP‑1559 basefee: For Cycles and Cells independently, basefee adjusts per block based on prior utilization; the basefee portion is burned and tips are paid to the proposer. (CIP‑3)
* Tip market: Users specify per‑meter tips to compete for inclusion; producers prioritize by effective tip. (CIP‑3)

***

## Validator Behavior

* Blocks must obey consensus and protocol rules; invalid blocks are rejected by honest nodes. Economic penalties, if any, are outside the scope of these limits.

***

## Off‑Chain Compute Constraints

* Result schema: Each off‑chain task includes a mandatory `result_schema` that defines output constraints (e.g., `max_return_bytes`, data format) for objective validation and DoS resistance. (CIP‑2)
* Deferred callbacks: Once N results are collected, a deferred transaction executes the callback in a future block, isolating on‑chain processing from off‑chain variability. (CIP‑2, CIP‑1)

***

## Protection Summary

| Vector           | Mechanism                                    | Source |
| ---------------- | -------------------------------------------- | ------ |
| **Compute DoS**  | `cycles_limit` metering and halting          | CIP‑3  |
| **Data DoS**     | `cells_limit` charged at I/O boundaries      | CIP‑3  |
| **Timer load**   | Per‑block timer processing budget; carryover | CIP‑1  |
| **Fee pressure** | Dual EIP‑1559 basefee + tips                 | CIP‑3  |

***

## Operational Notes

* Node implementations may expose observability metrics, but these are client‑specific and non‑normative. The consensus‑critical limits remain those defined by the protocol. (Scope clarification)

***

## Developer Guidance (Non‑Normative)

* Prefer algorithms and data structures that reduce Cycles and Cells usage.
* Store large artifacts off‑chain and reference them by content hash.
* Estimate resource usage before submitting transactions; set `cycles_limit` and `cells_limit` with appropriate headroom.

***

## Further Reading

* [Fee Model Overview](/architecture/fees/overview)
* [Actor VM Resource Limits](/architecture/actor-vm/resource-limits)
* [Off-Chain Lifecycle](/architecture/offchain/lifecycle)
* [CIP-1](/cips/cip-1)
* [CIP-2](/cips/cip-2)
* [CIP-3](/cips/cip-3)

***

## FAQ (Non‑Normative)

<AccordionGroup>
  <Accordion title="What happens if I exceed a resource limit?" icon="triangle-exclamation">
    The transaction fails when a consensus‑critical limit is reached (see CIP‑3 for Cycles/Cells). Estimate usage and set appropriate limits.
  </Accordion>

  <Accordion title="How should I handle large data?" icon="file-arrow-up">
    Prefer off‑chain storage for large artifacts and reference them on‑chain via content hashes. This reduces on‑chain data costs while preserving integrity.
  </Accordion>
</AccordionGroup>