> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superearn.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Multichain safety design: Runespear

> Runespear is the “air‑traffic control” for SuperEarn’s cross‑chain funds. It makes sure deposits, yields, and withdrawals stay correctly accounted for even while assets and messages move on different chains.

## Summary

* Multichain systems are inherently asynchronous: messages and assets move on separate timelines.
* Runespear solves this by:

  * Standardizing cross‑chain messages
  * Piggybacking full state snapshots on every message
  * Using a conservative accounting model that avoids double counting
* SuperEarn is built so that **asset safety and correctness come first**, even in the face of delays or partial failures in CCIP or bridges.

## 1. Why Multichain Is Hard

When SuperEarn uses more than one blockchain (for example, Kaia for the user interface and Ethereum for deep liquidity), two things travel separately:

* **Messages** – “Do this action” (deposit, withdraw, update state)
* **Assets** – USDT/USDC actually moving through a bridge

These two rails…

* Don’t arrive at the same time
* Can be delayed, retried, or temporarily fail independently
* May be processed in slightly different orders on each chain

Without a good design, this can cause:

* Temporary **double counting** of assets (appearing in two places)
* Confusing balances if a message or bridge transfer is delayed
* Fragile systems that “freeze” if one chain or service is slow

Runespear is SuperEarn’s solution to this problem.

***

## 2. What Is Runespear?

Runespear is a **standardized messaging layer** that sits between SuperEarn’s vaults and the cross‑chain infrastructure, built on top of Chainlink CCIP.

At a high level, it:

* Lets chains send **clear, typed instructions** to each other (e.g., “these many assets were bridged”, “withdrawal confirmed”)
* Attaches a **full state snapshot** to every message, so each side always has an up‑to‑date picture of the system
* Automatically handles **retries and failed messages** instead of silently breaking

You can think of it as a shared language and ledger for SuperEarn chains to talk to each other safely.

***

## 3. Safety Goals

Runespear and the SuperEarn V2 architecture are designed with a few clear goals:

1. **Never lose or double‑count funds**:
   Total assets across chains should always be mathematically consistent, even during bridge transfers.

2. **Stay safe under delays or outages**:
   If CCIP or a bridge is slow, the system uses the last safe data and corrects itself as soon as new information arrives.

3. **Avoid “stop‑the‑world” behavior**:
   User‑facing functions like reading your balance should never have to “wait” on another chain to respond.

4. **Minimize trust assumptions**:
   Runespear treats both CCIP and bridges as external infrastructure and is designed to remain safe even if they delay or fail to call back.

***

## 4. Two Rails, One Coherent Picture

SuperEarn’s cross‑chain design separates responsibilities into layers:

* **Vaults (per chain)** – Hold and manage funds on each chain
* **Message Agent** – Translates vault actions into cross‑chain messages
* **Crosschain Adapter** – Talks to CCIP and the native bridge
* **Runespear / CCIP + Bridge** – The actual infrastructure that transports messages and assets

From a user’s point of view this is invisible, but it matters for safety:

* Vaults only deal with **local, verified balances**
* Runespear and the adapter are responsible for **keeping both sides in sync** over time

***

## 5. State Snapshots on Every Message

The most important safety feature is **“universal state piggybacking.”**

Every Runespear message carries:

* The action (for example, “bridge complete”, “sync balances”)
* A **state snapshot** of what the sending chain currently believes:

  * How many assets are held in the vault
  * What’s currently in transit via the bridge
  * Relevant timestamps and markers

This gives the receiving chain a **complete, up‑to‑date picture** every time a message arrives, not just a small delta.

**Why this is safe:**

* If a message is delayed or lost, the **next** message still contains a fresh snapshot.
* The system doesn’t need to “chain” updates in a perfect order; it always overwrites with the latest known truth.
* This makes the system **self‑correcting** – it naturally converges back to correct accounting as soon as messages resume.

***

## 6. Correct Balances Without Freezing the System

In cross‑chain systems, there’s a tempting but dangerous idea:

> “Don’t let anyone move until we get fresh data from the other chain.”

This “stop‑the‑world” approach is **not** what SuperEarn does. It would:

* Make basic reads (like `totalAssets`) slow or unreliable
* Force every call to wait on external systems
* Break integrations with other protocols that expect instant, read‑only functions

Instead, SuperEarn:

1. **Trusts local, on‑chain data first**:
   Each chain knows exactly how much it holds **locally**.

2. **Combines it with the latest snapshot from the other chain**:
   Using the state snapshots carried by Runespear messages.

3. **Avoids double counting "in‑flight" transfers**:
   During bridging, some assets are moving between chains. SuperEarn's accounting model detects and subtracts this overlap so the same funds are never counted twice.

4. **Never blocks user‑facing reads**:
   Even if messages are temporarily delayed, balance queries still return immediately, using the last safe, conservative data.

Real‑world analogy:

* Imagine two branches of the same bank.
* Each branch keeps its own local ledger, and they periodically reconcile.
* You can still withdraw from your branch even if the other branch is slow to respond.
* Over time, the ledgers converge and every unit of money is accounted for.

That’s essentially how SuperEarn behaves under Runespear.

***

## 7. How Runespear Handles Failure Scenarios

Here’s how the system behaves under common “bad” conditions:

### 7.1 Message Delays or Loss

If a CCIP/Runespear message is delayed or fails:

* The system **stores** information about the failed message for inspection and possible retry.
* Later messages still carry **full snapshots**, which allow the system to resync correctly.
* User‑facing views remain available, using the last safe state.

### 7.2 Bridge Congestion or Outage

If the native bridge between chains is slow or temporarily down:

* Transfers in progress are tracked in a **bridge queue** and via the accounting layer.
* Assets are not assumed “arrived” until the system can clearly see them on the target chain.
* Total assets remain mathematically consistent; at worst, some funds are treated as “in transit” for longer.

### 7.3 Remote Chain Issues

If the remote chain is congested or temporarily unavailable:

* Origin‑side operations that depend on remote info can become more conservative, but **do not corrupt accounting**.
* Once Runespear messages resume, the new snapshots automatically reconcile any missed intermediate steps.

***

## 8. What This Means for Users

From a user’s perspective:

* You simply **deposit** on Kaia, yields are generated across chains, and you **withdraw** back to Kaia.
* Behind the scenes, Runespear:

  * Keeps the different chains in sync using state snapshots
  * Handles delays, retries, and ordering issues
  * Makes sure your funds aren’t under-counted or “lost in transit”

In practice, this means:

* Balances might be **slightly conservative** for short periods during heavy cross‑chain activity.
* But they are designed to be:

  * **Safe** – never overstated or double‑counted
  * **Eventually exact** – they converge to the true value once all messages and transfers settle

***