Merge pull request #313 from CoinFabrik/migrate-dos-unbounded-operati…

…on-documentation

New dos-unbounded-operation documentation

docs/docs/detectors/11-dos-unbounded-operation.md

@@ -1,43 +1,56 @@
 # DoS unbounded operation
 
-### What it does
+## Description 
 
-This detector checks that when using for or while loops, their conditions limit the execution to a constant number of iterations.
+- Category: `Denial of Service`
+- Severity: `Medium`
+- Detector: [`dos-unbounded-operation`](https://github.com/CoinFabrik/scout-soroban/tree/main/detectors/dos-unbounded-operation)
+- Test Cases: [`dos-unbounded-operation-1`](https://github.com/CoinFabrik/scout-soroban/tree/main/test-cases/dos-unbounded-operation/dos-unbounded-operation-1) [`dos-unbounded-operation-2`](https://github.com/CoinFabrik/scout-soroban/tree/main/test-cases/dos-unbounded-operation/dos-unbounded-operation-2) [`dos-unbounded-operation-3`](https://github.com/CoinFabrik/scout-soroban/tree/main/test-cases/dos-unbounded-operation/dos-unbounded-operation-3)
+
+Each block in a Stellar Blockchain has an upper bound on the amount of gas that can be spent, and thus the amount computation that can be done. This is the Block Gas Limit. 
 
-### Why is this bad?
+## Why is this bad? 
 
-If the number of iterations is not limited to a specific range, it could potentially cause out of gas exceptions.
+If the number of iterations is not limited to a specific range, it could potentially cause out of gas exceptions. If this happens, gas will leak, the transaction will fail, and there will be a risk of a potential attack on the contract.
 
-### Known problems
+## Issue example
 
-False positives are to be expected when using variables that can only be set using controlled flows that limit the values within acceptable ranges.
+In the following example, a contract has a function ´unsafe_loop_with_array´, which contains a for loop that iterates over a range of numbers from 0 to the lenght of the array ´unknown_array´. The issue is that if the length of the array is extremely large, it would cause the loop to execute many times, potentially leading to an unusable state of the contract.
 
-### Example
+Consider the following `Soroban` contract:
 
 ```rust
-pub fn unrestricted_loop(for_loop_count: u64) -> u64 {
-    let mut count = 0;
-    for i in 0..for_loop_count {
-        count += i;
+ pub fn unsafe_loop_with_array(unknown_array: BytesN<8>) -> u32 {
+        let mut sum = 0;
+        for i in 0..unknown_array.len() {
+            sum += i;
+        }
+        sum
     }
-    count
-}
 ```
+The code example can be found [here](https://github.com/CoinFabrik/scout-soroban/tree/main/test-cases/dos-unbounded-operation/dos-unbounded-operation-3/vulnerable-example).
 
-Use instead:
 
-```rust
-const FIXED_COUNT: u64 = 1000;
+## Remediated example
 
-pub fn restricted_loop_with_const() -> u64 {
-    let mut sum = 0;
-    for i in 0..FIXED_COUNT {
-        sum += i;
+To solve this, instead of relying on an external parameter, we should introduce a known value directly into the loop.
+```rust
+ pub fn safe_loop_with_array() -> u64 {
+        let mut sum = 0;
+        let known_array = [0; 8];
+        for i in 0..known_array.len() {
+            sum += i;
+        }
+        sum as u64
     }
-    sum
-}
 ```
 
-### Implementation
+The remediated code example can be found [here](https://github.com/CoinFabrik/scout-soroban/tree/main/test-cases/dos-unbounded-operation/dos-unbounded-operation-3/remediated-example).
+
+## How is it detected?
+
+This detector checks that when using for or while loops, their conditions limit the execution to a constant number of iterations.
+
+
 
-The detector's implementation can be found at [this link](https://github.com/CoinFabrik/scout-soroban/tree/main/detectors/dos-unbounded-operation).
+