# Functions

### General Execution Flow 

Helios exposes a small set of user-facing entry points in **Pool.sol**—`supply`, `withdraw`, `borrow`, `repay`, `liquidate`, and so on.\
Although each function has its own validation rules, almost every call follows the same five-step template shown below. Understanding this pattern makes it much easier to reason about gas costs, interest updates, and edge-case protections when you integrate Helios into a dApp or trading bot.

***

#### 1 · Standard Path for State-Changing Calls

```
cache      →  updateState  →  validate  →  changeState  →  updateRates
```

| Step            | What happens                                                                                       | Why it matters                                                          |
| --------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **cache**       | Load frequently used storage slots (e.g., reserve configuration, user data) into stack variables.  | Minimises SLOADs and keeps later checks cheap.                          |
| **updateState** | Accrue interest for every reserve by updating the liquidity and borrow indexes.                    | Ensures all subsequent checks use up-to-date debt & collateral figures. |
| **validate**    | Confirm the action is allowed after the state refresh (caps, health-factor, isolation-mode, etc.). | Guarantees protocol invariants before any tokens move.                  |
| **changeState** | Mint/burn hTokens or debt tokens, move BTC in / out of the pool, toggle collateral flags, etc.     | Executes the user’s intent once it is proven safe.                      |
| **updateRates** | Re-compute borrow & supply APRs based on the new utilisation.                                      | Keeps the next transaction priced correctly.                            |

***

#### 2 · Flash-Loan Exception

Flash-loans invert the first part of the sequence to defend against re-entrancy and rate manipulation inside the borrower’s callback:

```
validate  →  userPayload  →  cache  →  updateState  →  changeState  →  updateRates
```

1. **validate** ensures the loan amount is available and fee parameters are sane.
2. **userPayload** executes the borrower’s arbitrary logic (swaps, arbitrage, etc.).
3. The usual *cache → updateState → changeState → updateRates* steps then settle the loan and apply fees, all in the same transaction.

***

#### 3 · Common Helper Functions

Most state-changing flows rely on the following internal helpers, which are documented in separate sections of this book:

| Helper                              | Purpose                                        |
| ----------------------------------- | ---------------------------------------------- |
| `cache()`                           | Pull reserve & user data into memory.          |
| `updateState()`                     | Accrue interest and bump the global indexes.   |
| `updateRates()`                     | Re-price borrow & supply APRs after an action. |
| `getFlags()`                        | Return bit-packed reserve configuration flags. |
| `getDecimals()`                     | Fetch token decimals once, reuse everywhere.   |
| `getSupplyCap()` / `getBorrowCap()` | Enforce governance-set caps on liquidity.      |

***

#### 4 · Why the Pattern Matters

* **Predictability** — Every high-level action hits the same checkpoints, so auditors and integrators have a single mental model.
* **Gas efficiency** — Caching and batched index updates avoid redundant storage reads/writes.
* **Safety** — Interest is always up-to-date *before* collateral or debt checks, preventing time-skew exploits.
* **Extensibility** — Because the rate update is last, new interest-rate strategies can be swapped in without touching earlier logic.

***

#### 5 · Takeaways for Builders

* Call any Pool function with confidence that interest and caps are refreshed inside the tx.
* If you use flash-loans, design your callback with the ordering reversal in mind—re-entrancy guards come from the routing, not your payload.
* For advanced analytics, hook into the `ReserveDataUpdated` event emitted during **updateRates** to track real-time APR changes.


---

# Agent Instructions: 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:

```
GET https://helios-finance.gitbook.io/helios-finance/for-developers/functions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.