> For the complete documentation index, see [llms.txt](https://docs.velthoryn.site/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.velthoryn.site/architecture-decisions/adr-fe-004-bankrun-ordering.md).

# ADR-FE-004: Bankrun Ordering

**Status:** Accepted

## Context

Bankrun integration tests use `context.setClock()` to advance simulated time for vesting unlock logic. `setClock()` updates the Solana clock sysvar but does NOT advance the bank's blockhash ring. When two consecutive transactions carry identical instruction data and are submitted at the same slot, they produce the same Ed25519 signature (same message bytes = same signature). The Solana runtime rejects the second transaction as "Transaction already been processed" -- a deterministic (not flaky) failure on the 2nd and 3rd claims in progressive fractional claim tests.

## Decision

Always call `context.warpToSlot(nextSlot)` before `context.setClock()` in the `warpClock()` helper at `tests/utils/bankrun.ts`. The slot increment produces a new blockhash-ring entry, ensuring subsequent transactions have a distinct `recentBlockhash` and therefore a different signature even when instruction data is identical.

## Consequences

**Positive:**

* All bankrun integration tests are deterministic. Progressive fractional claims, multi-checkpoint `withdraw`, and multi-step milestone vesting tests pass consistently across all environments.
* `warpClock()` in `tests/utils/bankrun.ts` is the single authoritative utility for time manipulation. Callers must not call `setClock()` directly.

**Negative:**

* The slot increment (1 slot is approximately 400ms simulated time) has no material effect on vesting math in existing tests.

## Alternatives Considered

* **`MOCHA_RETRIES=2`:** The failure is deterministic, so retrying the same slot produces the same failure. Retries hide the bug rather than fixing it.
* **Add a nonce to instruction data:** Would make transactions unique but pollutes the instruction interface with test-only fields.
* **Random `recentBlockhash`:** Not possible in bankrun; the blockhash must come from the bank's ring.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.velthoryn.site/architecture-decisions/adr-fe-004-bankrun-ordering.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.