> For the complete documentation index, see [llms.txt](https://docs.symm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.symm.io/contract-documentation/symmio-perps-v0.8.5/diamond-core-facets/migration.md).

# Migration

The Migration Facet provides one-time data migration functions needed when upgrading from v0.8.4 to v0.8.5. Two features require existing storage to be backfilled: **Cross PartyB Mode** (unified balance management across all PartyAs) and **Aggregated Positions** (uPnL and funding calculations).

***

#### Overview

The Migration Facet provides:

* **Quote Migration:** Populates aggregated position and funding structures from existing open quotes, initializes new quote fields (`accumulatedPaidFunding`), and backfills PartyB total position counters and PartyA↔PartyB connection caches.
* **Cross Locked Values Migration:** Sums per-PartyA balances (allocated, locked, pending locked) into the cross bucket (`address(0)`) for PartyBs that will operate in cross mode.
* **Verification Views:** Check whether individual quotes or PartyB balances have been migrated.

***

#### Why Migration Is Needed

**Aggregated Positions:** In v0.8.4, calculating uPnL and funding debt required iterating every open quote (O(quotes) complexity). v0.8.5 introduces per-symbol aggregated position structures that enable O(symbols) calculations. Migration populates these structures from existing open positions.

**Cross PartyB Mode:** In v0.8.4, PartyB balances are tracked separately per PartyA. v0.8.5 introduces a unified "cross bucket" keyed by `address(0)` that aggregates all per-PartyA balances. When cross mode is enabled for a PartyB, solvency checks use this cross bucket, allowing unified capital management. Migration sums the existing per-PartyA balances into this bucket.

***

#### migrateQuotes()

Backfills v0.8.5 derived state for a batch of existing quotes. Can be called multiple times with different batches. Already-migrated quotes are silently skipped (idempotent). Only active quotes (status `OPENED`, `CLOSE_PENDING`, or `CANCEL_CLOSE_PENDING`) are processed; non-active quotes are skipped.

For each active quote, the function:

* Initializes `accumulatedPaidFunding` based on current funding rates
* Adds to `partyBAggregatedPositions` and `partyAAggregatedPositions` (per-symbol totals)
* Updates `activeSymbols` arrays for both parties
* Adds to aggregate funding structures (`weightedPaidFunding` counters)
* Updates the PartyB total positions counter (`partyBPositionsCount[partyB][address(0)]`)
* Populates the PartyA↔PartyB connection cache

**Function Signature:**

```solidity
function migrateQuotes(uint256[] calldata quoteIds) external onlyRole(MIGRATION_ROLE);
```

**Parameters:**

* `quoteIds`: Array of quote IDs to migrate. Typically all open quotes, processed in batches.

**Access:** Requires `MIGRATION_ROLE`.

**Example:**

```solidity
// Migrate quotes in batches of 100
uint256[] memory batch = getOpenQuoteIdsBatch(0, 100);
symmDiamond.migrateQuotes(batch);
```

**Events Emitted:**

* `QuotesMigrated(uint256 totalQuotes, uint256 quotesMigrated)`: `totalQuotes` is the batch size, `quotesMigrated` is how many were actually processed (excludes already-migrated and non-active quotes).

***

#### migrateCrossLockedValues()

Aggregates per-PartyA balances into the cross bucket (`address(0)`) for a specific PartyB. Should be called while the system is paused during the upgrade. Reverts if called twice for the same PartyB (marks the PartyB as migrated to prevent double-counting).

For each PartyA provided, the function sums:

* `partyBAllocatedBalances[partyB][partyA]` → `partyBAllocatedBalances[partyB][address(0)]`
* `partyBLockedBalances[partyB][partyA]` → `partyBLockedBalances[partyB][address(0)]`
* `partyBPendingLockedBalances[partyB][partyA]` → `partyBPendingLockedBalances[partyB][address(0)]`

**Function Signature:**

```solidity
function migrateCrossLockedValues(address partyB, address[] calldata partyAs) external onlyRole(MIGRATION_ROLE);
```

**Parameters:**

* `partyB`: The PartyB address to migrate.
* `partyAs`: All PartyA addresses that have positions or balances with this PartyB.

**Access:** Requires `MIGRATION_ROLE`.

**Events Emitted:**

* `CrossLockedValuesMigrated(address partyB, uint256 partyAsProcessed)`

***

#### isQuoteMigrated()

View function to check whether a specific quote has been migrated.

**Function Signature:**

```solidity
function isQuoteMigrated(uint256 quoteId) external view returns (bool);
```

**Parameters:**

* `quoteId`: The quote ID to check.

**Returns:** `true` if the quote has been migrated.

***

#### isPartyBLockedValuesMigrated()

View function to check whether a PartyB's per-PartyA balances have been aggregated into the cross bucket.

**Function Signature:**

```solidity
function isPartyBLockedValuesMigrated(address partyB) external view returns (bool);
```

**Parameters:**

* `partyB`: The PartyB address to check.

**Returns:** `true` if the PartyB's locked values have been migrated.


---

# 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.symm.io/contract-documentation/symmio-perps-v0.8.5/diamond-core-facets/migration.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.