> For the complete documentation index, see [llms.txt](https://docs.northstar.sonicsvm.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.northstar.sonicsvm.org/architecture/er-topology.md).

# ER Topology

How a NorthStar session is wired across the user, the SDK, the L1 anchor, and the Ephemeral Rollup. This page covers the **components** and the **data path** for the canonical session lifecycle: open → delegate → execute → settle.

## The components

| Component                 | Where it lives                 | Role                                                                                                                                                    |
| ------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User / dApp**           | Browser, agent runtime, server | Initiates session lifecycle and submits transactions. Holds the owner keypair.                                                                          |
| **NorthStar SDK**         | Same process as the user       | Wraps the Portal program and the ER RPC. Translates `openSession`, `delegate`, `closeSession` into the corresponding Solana ixs.                        |
| **Router**                | Edge                           | Routes ER-bound traffic to the right validator instance (the `(portal, owner, grid_id)` tuple identifies the session).                                  |
| **Portal (L1)**           | Solana L1 program              | Source of truth for session metadata, delegation records, and settle-back. Locks delegated accounts on L1 for the session's lifespan.                   |
| **Validator**             | Operator infrastructure        | A single-tenant Solana validator dedicated to the session. Spawns on `SessionCreated`, processes ER txs, holds the canonical session state until close. |
| **Ephemeral Rollup (L2)** | Inside the validator           | The runtime where ER transactions execute. Same SVM semantics as L1 — different slot cadence, different fee policy.                                     |

## The data flow

The diagram below traces a full session lifecycle. The columns are actors; time runs top to bottom.

![NorthStar data flow](/files/sEI7TUfadtpnmV1GW32w)

Five message phases:

### 1. `openSession`

The owner calls `sdk.openSession({ gridId, ttlSlots, feeCap, feeStructure })`. The SDK assembles the Portal `OpenSession` ix and submits it to L1. The Portal:

* Creates the session PDA at `sessionPda(portal, owner, grid_id)`.
* Creates a per-owner `fee_vault` PDA (one-time per owner).
* Pulls the `feeCap` lamports from the owner into the fee vault.
* Emits a `SessionCreated` event.

The validator subscribes to that event and **spawns the ER runtime** for this session. From this point until close, every account delegated to this session is exclusive to this validator instance.

### 2. `delegateAccount`

For each account the session needs to write, the owner calls `sdk.delegate({ account, ownerProgram })`. The Portal:

* Reassigns the account's `owner` field to the Portal program. **This locks it on L1.**
* Creates a delegation record at `delegationRecordPda(portal, account)` with `(grid_id, owner_program, bump)`.
* Emits an `AccountDelegated` event.

The validator picks the event up and marks the account writable inside the ER. Reads come from L1 state at delegation time; writes accumulate locally.

### 3. `sendTransaction`

The owner — or any keypair the session-side program accepts — submits a transaction to the ER's RPC. The Router forwards it to the validator instance hosting this session. The validator:

* Validates the tx against ER state and the session's delegated set.
* Executes inside the SVM at the session's slot cadence.
* Confirms back to the SDK over WebSocket (`signatureSubscribe`).

End-to-end confirmation latency on the same machine as the validator is sub-50ms; over the public internet it floors at the network round-trip. See [real-time confirmation](/architecture/real-time.md) for the breakdown.

### 4. `closeSession`

When the owner calls `sdk.closeSession({ gridId })` (or the TTL expires), the Portal initiates settlement:

* The validator stashes the final state of every delegated account.
* The Portal walks the delegation set and applies each final state to its corresponding L1 account in a single multi-account write.
* Ownership is restored to the original program.
* Each delegation record is closed; rent flows back to the owner.

The settle is **all-or-nothing**: either every delegated account commits its final state, or none do and the session reverts to its pre-close state for retry. See [settle-back guarantees](/concepts/settle-back.md) for the failure modes.

### 5. State settled on L1

After the Portal finalizes settlement, the post-session state is the canonical L1 state. Anyone can read it; the original owners can write it again. The session is gone.

## What stays on L1, what's local to the ER

| State                                          | While session is active       | After close                                                 |
| ---------------------------------------------- | ----------------------------- | ----------------------------------------------------------- |
| **Delegated accounts**                         | Writable in ER, locked on L1  | L1 receives final ER state; ownership restored              |
| **Non-delegated accounts**                     | Read-only in ER, normal on L1 | Unaffected                                                  |
| **Session PDA, fee vault, delegation records** | Live on L1 throughout         | Reaped on close (rent → owner)                              |
| **ER block history**                           | Held by the validator         | Discarded on close (the L1 state is the canonical artifact) |

This is what makes the ER **ephemeral**: the canonical state lives on L1; the ER is a fast, scoped execution environment that exists only for the session's lifespan.

## Per-component failure handling

| Component fails               | What happens                                                                                                                                  |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| User goes offline mid-session | No effect — the ER continues until close or TTL.                                                                                              |
| SDK process dies              | Same — restart and reconnect to the same `(owner, grid_id)`.                                                                                  |
| Router goes down              | ER traffic queues at the edge; recovers when the route is restored.                                                                           |
| Validator process crashes     | The ER stalls. State persists in the validator's WAL. The validator restarts and resumes; if it can't, the owner force-undelegates after TTL. |
| Validator host fails entirely | Same as above — the operator restores; if recovery is impossible, the owner force-undelegates.                                                |
| Portal or L1 down             | The session's existing ER work isn't blocked — execution continues — but new opens, delegations, and closes wait for L1.                      |

The single-tenant property limits blast radius: any failure is scoped to one session.

## See also

* [Sessions](/concepts/sessions.md) — the session as a first-class object.
* [Account delegation](/concepts/delegation.md) — what makes an account writable on the ER.
* [Real-time confirmation](/architecture/real-time.md) — slot cadence and the ER confirmation path.
* [Security model](/architecture/security.md) — how the trust assumptions hold up under adversarial conditions.
* [Portal program reference](/reference/portal-program.md) — the on-chain ix surface.


---

# 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.northstar.sonicsvm.org/architecture/er-topology.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.