---
name: "temporal-parameter-staleness"
description: "Trigger Pattern interval|period|duration|delay|cooldown|lock_period|timelock|unbonding|claim_delay|withdraw_delay|maturity|ledger_sequence|timestamp - Inject Into Breadth agents, depth-state-trace"
---

# TEMPORAL_PARAMETER_STALENESS Skill (Soroban)

> **Trigger Pattern**: `interval|period|duration|delay|cooldown|lock_period|timelock|unbonding|claim_delay|withdraw_delay|maturity|ledger_sequence|timestamp`
> **Inject Into**: Breadth agents, depth-state-trace
> **Finding prefix**: `[TPS-N]`
> **Rules referenced**: R2, R8, R10, R13, R14

Cached parameters in multi-step operations become stale when authority changes them between steps. On Soroban, timing has unique properties: `env.ledger().timestamp()` provides Unix seconds (estimated, can lag wall clock), `env.ledger().sequence_number()` provides the exact ledger number (strictly monotonic), SCP consensus closes ledgers approximately every 5 seconds, and there is no concept of slots, epochs, or a clock sysvar. TTL (time-to-live) is measured in ledger numbers and can itself act as a timing mechanism.

---

## Step 1: Enumerate Multi-Step Operations

Find all operations that span multiple transactions (ledgers):

| Operation | Step 1 (Initiate) | Wait Condition | Step N (Complete) | Clock Source |
|-----------|-------------------|----------------|-------------------|-------------|
| {op_name} | {initiate_fn}() | {condition} | {complete_fn}() | ledger_sequence / timestamp |

For each multi-step operation:
- What parameters are read/cached at Step 1 (stored in Persistent/Instance storage)?
- What parameters are re-read at Step N?
- What parameters are used but NOT re-read at Step N?
- **Which clock source is used?** (`env.ledger().timestamp()` vs `env.ledger().sequence_number()`)

### Soroban Clock Semantics

| Clock Source | Type | Resolution | Monotonicity | Accuracy | Typical Use Case |
|-------------|------|-----------|-------------|----------|-----------------|
| `env.ledger().sequence_number()` | `u32` | ~5s per ledger | Strictly increasing | Exact (validator-produced) | Cooldowns, lock periods, rate-limiting |
| `env.ledger().timestamp()` | `u64` (Unix seconds) | ~5s | Mostly increasing (can lag) | Estimated by SCP; may lag wall clock by seconds to minutes during network stress | Human-readable delays, longer durations |

**Critical property**: Within a single transaction (a single invocation tree, including sub-invocations via `invoke_contract`), ALL calls see the same `env.ledger()` values — there is no intra-transaction timing variation. Multi-step timing attacks require separate ledgers (separate transactions).

**Timestamp vs sequence tradeoff**:
- `timestamp` is human-intuitive (seconds) but can lag real time during validator slowdowns
- `sequence_number` is exact but requires converting to human time (~5s per ledger, subject to change if Stellar network parameters change)
- Hardcoded `sequence_number` durations break if Stellar's ledger close time changes (currently ~5s, configurable by validators)

---

## Step 2: Identify Cached Parameters

For each parameter used across steps:

| Parameter | Storage Type + Key | Read At Step | Cached in User State? | Admin-Changeable? | Re-Validated At Completion? |
|-----------|-------------------|-------------|----------------------|------------------|-----------------------------|
| {param} | {Instance/Persistent, DataKey::Foo} | initiate() | YES/NO | YES/NO (which function) | YES/NO |

**Soroban caching patterns**:
- **Instance storage cache**: User's position struct stores a snapshot of config params at initiation time (e.g., `position.fee_rate = config.fee_rate` at deposit time)
- **Persistent storage cache**: Per-user Persistent entry stores the start ledger or timestamp (e.g., `user_position.start_ledger = env.ledger().sequence_number()`)
- **Re-read pattern**: Step N re-reads from Instance storage directly — no staleness for that param
- **Allowance TTL as cached permission**: An allowance stored in Temporary storage expires by `expiration_ledger` — if the operation takes longer than expected, the allowance expires and Step N fails

**Red flags**: Parameter is cached in user's Persistent entry at Step 1 AND admin can change the source config AND Step N does NOT re-read from source.

---

## Step 3: Model Staleness Impact

For each cached parameter that can become stale:

```
Scenario A: Parameter INCREASES between steps
1. User initiates at Step 1 — user Persistent entry stores param = X
2. Admin updates Instance config: param = X + delta
3. User completes at Step N — uses cached X from Persistent entry
4. Impact: {what happens with stale X when current config is X + delta}

Scenario B: Parameter DECREASES between steps
1. User initiates at Step 1 — user Persistent entry stores param = X
2. Admin updates Instance config: param = X - delta
3. User completes at Step N — uses cached X
4. Impact: {what happens with stale X when current config is X - delta}
```

**BOTH directions are mandatory** — increase and decrease often have different impacts.

### Soroban-Specific Staleness Vectors

| Vector | Description | Severity Modifier |
|--------|-------------|-------------------|
| **TTL expiry window** | User position's Persistent entry expires (archived) during a long multi-step operation. Step N read panics or returns stale default. | HIGH if position data lost; MEDIUM if restorable |
| **Ledger sequence drift** | Protocol uses hardcoded ledger counts for delays; Stellar network changes average ledger time. Delays become longer or shorter than intended in wall-clock seconds. | Medium if delay is safety-critical (e.g., withdrawal delay shorter than market manipulation window) |
| **Timestamp lag** | `env.ledger().timestamp()` lags wall clock during network stress. Tight timestamp comparisons (<60s) may behave unexpectedly. | Medium if tight comparisons used |
| **Config upgraded mid-operation** | Admin upgrades contract wasm between Step 1 and Step N. New wasm reads cached params differently. | High — storage layout changes can corrupt cached position |
| **Instance TTL expiry** | Instance storage (holding config) expires during a long operation. Step N reads config and panics. | MEDIUM — affects all users simultaneously |

---

## Step 3b: Update Source Audit

For each parameter updated from an external source (oracle contract, price feed):
- Is the source the correct representation of what this parameter tracks?
- **Is the source contract address validated?** Can a fake oracle be substituted via a user-supplied address?
- Should this parameter be fixed for a period (e.g., per epoch cycle) rather than continuously refreshed?
- Which functions update it? Which SHOULD? Any mismatch?
- **Is there a `refresh` or `crank` function?** Who calls it and when? What is the protocol state if it is never called?

---

## Step 4: Retroactive Application Analysis

For fee/rate parameters that apply to existing state:

| Parameter | Storage Key | Applies To | Retroactive? | Impact |
|-----------|------------|-----------|--------------|--------|
| {fee_param} | {DataKey::FeeBps} | {what it affects} | YES/NO | {if retroactive: who is harmed} |

**Soroban retroactive patterns**:
- **Instance config update**: Admin changes `fee_bps` in Instance storage. All pending claims calculated at completion time using new rate — retroactively changes expected returns for users who initiated under old rate.
- **Cooldown ledger update**: Admin changes `cooldown_ledgers` in config. Users who initiated cooldown under old value may now need to wait longer or shorter — retroactive effect on in-flight positions.
- **Rate-at-close pattern**: If the protocol reads the current config rate at Step N (not the cached rate from Step 1), any admin change between steps applies retroactively to all pending operations.

**Rule 2 direction check**: Can the admin's parameter change make a user-facing function behave unexpectedly? (e.g., setting `cooldown_ledgers = 0` removes withdrawal protection entirely; setting `max_withdrawal = 0` blocks all withdrawals). Does the change retroactively affect users in active positions?

---

## Step 5: Assess Severity

For each staleness issue:
- **Who is affected?** (single user, all users with pending operations, protocol)
- **Is the impact bounded?** (capped by parameter range, max delay, etc.)
- **Can it be exploited intentionally?** (admin or operator timing changes to specific ledgers)
- **Is there a recovery path?** (cancel and re-initiate, admin override)
- **Ledger precision**: Given ~5s ledger close time, how precisely can an attacker time the exploitation?

### Severity Assessment (Rule 10 — Worst-State)

Use worst realistic operational state, not current on-chain snapshot:
```
Severity assessed at: pending_claims=MAX_USERS, fee_delta=MAX_FEE-MIN_FEE, tvl=$XXM
Rationale: Protocol designed for up to {N} concurrent pending operations per documentation
```

---

## Key Questions (must answer all)

1. What multi-step operations exist? (initiate/claim, deposit/cooldown/withdraw, propose/execute)
2. For each cached parameter: can admin change it between steps?
3. What happens if a delay DECREASES after initiation? (users can complete too early relative to new policy)
4. What happens if a delay INCREASES after initiation? (users locked longer than originally expected)
5. Are fees applied retroactively to existing positions or only to new ones?
6. Is there a maximum parameter range that bounds the staleness impact?
7. **Soroban-specific**: Does the protocol use `sequence_number` or `timestamp` for timing? If `timestamp`, is potential lag handled?
8. **Soroban-specific**: Does any Persistent storage entry have a TTL shorter than the longest expected operation? Can it expire mid-operation?
9. **Soroban-specific**: Is there a crank/refresh function? What happens if it is never called?
10. **Soroban-specific**: If the contract is upgraded between Step 1 and Step N, does the new wasm correctly interpret cached values from Persistent storage?

---

## Common False Positives

- **Immutable config**: If Instance storage has no update function or admin is revoked, no staleness
- **Bounded ranges**: If min/max bounds limit the change magnitude (enforced on-chain), impact may be Low
- **User can cancel**: If users can cancel pending operations and re-initiate, reduced severity
- **Timelock protection**: If parameter changes require a proposal+delay pattern, users have time to react
- **Same-transaction operations**: Operations completing within a single invocation tree cannot have clock staleness between steps
- **Re-read at completion**: If Step N re-reads directly from Instance storage (not a cached copy in Persistent), no staleness for that parameter

---

## Instantiation Parameters

```
{CONTRACTS}           - Contracts to analyze
{MULTI_STEP_OPS}      - Identified multi-step operations
{CACHED_PARAMS}       - Parameters cached at initiation (stored in user Persistent entries)
{ADMIN_PARAMS}        - Admin-changeable parameters in Instance storage
{DELAY_PARAMS}        - Delay/cooldown parameters (in ledger_sequence counts or timestamp seconds)
{FEE_PARAMS}          - Fee/rate parameters that may apply retroactively
{CLOCK_SOURCE}        - Clock source used (sequence_number / timestamp)
```

---

## Output Schema

| Field | Required | Description |
|-------|----------|-------------|
| multi_step_ops | yes | List of multi-step operations found |
| cached_params | yes | Parameters cached across steps (stored in which storage type + key) |
| staleness_vectors | yes | How cached params can become stale |
| retroactive_fees | yes | Fees applied retroactively |
| clock_source_audit | yes | Which clock source is used and whether appropriate |
| ttl_expiry_risks | yes | Storage entries that could expire mid-operation |
| finding | yes | CONFIRMED / REFUTED / CONTESTED |
| evidence | yes | Code locations with line numbers |
| step_execution | yes | Status for each step |

---

## Step Execution Checklist (MANDATORY)

| Step | Required | Completed? | Notes |
|------|----------|------------|-------|
| 1. Enumerate Multi-Step Operations | YES | | |
| 2. Identify Cached Parameters | YES | | |
| 3. Model Staleness Impact (both directions) | YES | | |
| 3b. Update Source Audit | YES | | |
| 4. Retroactive Application Analysis | YES | | |
| 5. Assess Severity | YES | | |

### Cross-Reference Markers

**After Step 2**: If cached parameters are admin-changeable → MUST complete Step 3 with BOTH increase and decrease scenarios.

**After Step 4**: Cross-reference with SEMI_TRUSTED_ROLES for admin functions that change these parameters.

**After Step 3**: If protocol uses `timestamp` for comparisons tighter than 60 seconds → FLAG clock lag concern.

**After Step 1**: If any Persistent storage entry has a TTL shorter than the longest expected operation → cross-reference with TTL expiry risk (Step 3 vector: TTL expiry window).