# MuonStorage (0.8.4)

The **MuonStorage** library provides a storage slot for Muon‑related configuration data. This storage is used by various LibMuon modules to retrieve settings such as signature validity periods, appl[^1]ication identifiers, public keys, and trusted gateway addresses.

***

### Data Structures

The following structures define the key signature and configuration data types used throughout the Muon ecosystem:

#### SchnorrSign

A Schnorr signature is used for cryptographic verification.

* **signature:** The actual signature (uint256).
* **owner:** The address of the entity that generated the signature.
* **nonce:** An additional parameter to ensure uniqueness (prevents replay attacks).

```solidity
struct SchnorrSign {
    uint256 signature;
    address owner;
    address nonce;
}
```

***

#### PublicKey

Represents a public key for signature verification.

* **x:** The x‑coordinate on the elliptic curve.
* **parity:** The parity of the y‑coordinate, enabling recovery of the full public key.

```solidity
struct PublicKey {
    uint256 x;
    uint8 parity;
}
```

***

#### SingleUpnlSig

Used for verifying a single unrealized profit and loss (uPnl) computation for one party.

* **reqId:** A unique identifier for the request.
* **timestamp:** The time the signature was generated.
* **upnl:** The calculated uPnl (can be positive or negative).
* **gatewaySignature:** A secondary signature from Muon.
* **sigs:** A SchnorrSign structure containing the primary signature.

```solidity
struct SingleUpnlSig {
    bytes reqId;
    uint256 timestamp;
    int256 upnl;
    bytes gatewaySignature;
    SchnorrSign sigs;
}
```

***

#### SingleUpnlAndPriceSig

Extends the single uPnl signature by including asset price information.

* **price:** The asset’s price used in uPnl verification.

```solidity
struct SingleUpnlAndPriceSig {
    bytes reqId;
    uint256 timestamp;
    int256 upnl;
    uint256 price;
    bytes gatewaySignature;
    SchnorrSign sigs;
}
```

***

#### PairUpnlSig

Contains uPnl values for two parties (Party A and Party B).

* **upnlPartyA:** uPnl for Party A.
* **upnlPartyB:** uPnl for Party B.

```solidity
struct PairUpnlSig {
    bytes reqId;
    uint256 timestamp;
    int256 upnlPartyA;
    int256 upnlPartyB;
    bytes gatewaySignature;
    SchnorrSign sigs;
}
```

***

#### PairUpnlAndPriceSig

Combines pair uPnl data with price information.

* **price:** The asset price relevant for both parties’ uPnl calculations.

```solidity
struct PairUpnlAndPriceSig {
    bytes reqId;
    uint256 timestamp;
    int256 upnlPartyA;
    int256 upnlPartyB;
    uint256 price;
    bytes gatewaySignature;
    SchnorrSign sigs;
}
```

***

#### PairUpnlAndPricesSig

An extension that supports multiple symbols.

* **symbolIds:** An array of symbol identifiers.
* **prices:** An array of corresponding prices.

```solidity
struct PairUpnlAndPricesSig {
    bytes reqId;
    uint256 timestamp;
    int256 upnlPartyA;
    int256 upnlPartyB;
    uint256[] symbolIds;
    uint256[] prices;
    bytes gatewaySignature;
    SchnorrSign sigs;
}
```

***

#### DeferredLiquidationSig

Used for deferred liquidation scenarios where access revocation or delayed processing is needed.

* **liquidationBlockNumber:** Block number when insolvency was detected.
* **liquidationTimestamp:** Timestamp of insolvency.
* **liquidationAllocatedBalance:** The allocated balance at insolvency.
* **liquidationId:** Unique liquidation event identifier.
* **upnl:** The uPnl at the time of insolvency.
* **totalUnrealizedLoss:** The total loss triggering liquidation.
* **symbolIds & prices:** Arrays of involved symbol IDs and their prices.

```solidity
struct DeferredLiquidationSig {
    bytes reqId;
    uint256 timestamp;
    uint256 liquidationBlockNumber;
    uint256 liquidationTimestamp;
    uint256 liquidationAllocatedBalance;
    bytes liquidationId;
    int256 upnl;
    int256 totalUnrealizedLoss;
    uint256[] symbolIds;
    uint256[] prices;
    bytes gatewaySignature;
    SchnorrSign sigs;
}
```

***

#### LiquidationSig

Similar to DeferredLiquidationSig but used in immediate liquidation scenarios.

```solidity
struct LiquidationSig {
    bytes reqId;
    uint256 timestamp;
    bytes liquidationId;
    int256 upnl;
    int256 totalUnrealizedLoss;
    uint256[] symbolIds;
    uint256[] prices;
    bytes gatewaySignature;
    SchnorrSign sigs;
}
```

***

#### QuotePriceSig

Used for verifying price data for multiple quotes simultaneously.

* **quoteIds:** An array of quote identifiers.
* **prices:** Corresponding prices for each quote.

```solidity
struct QuotePriceSig {
    bytes reqId;
    uint256 timestamp;
    uint256[] quoteIds;
    uint256[] prices;
    bytes gatewaySignature;
    SchnorrSign sigs;
}
```

***

#### HighLowPriceSig

Provides detailed price range information for a single symbol.

* **symbolId:** Identifier for the trading symbol.
* **highest:** The highest observed price in the period.
* **lowest:** The lowest observed price in the period.
* **averagePrice:** The average price over a specified period.
* **startTime & endTime:** The time window during which the prices were observed.
* **currentPrice:** The current price used for calculations.
* **upnlPartyB & upnlPartyA:** uPnl values for both parties (if applicable).

```solidity
struct HighLowPriceSig {
    bytes reqId;
    uint256 timestamp;
    uint256 symbolId;
    uint256 highest;
    uint256 lowest;
    uint256 averagePrice;
    uint256 startTime;
    uint256 endTime;
    int256 upnlPartyB;
    int256 upnlPartyA;
    uint256 currentPrice;
    bytes gatewaySignature;
    SchnorrSign sigs;
}
```

***

#### QuoteSettlementData

Holds settlement-specific data for a quote.

* **quoteId:** The identifier of the quote.
* **currentPrice:** The price at settlement.
* **partyBUpnlIndex:** An index indicating which Party B's uPnl is used.

```solidity
struct QuoteSettlementData {
    uint256 quoteId;
    uint256 currentPrice;
    uint8 partyBUpnlIndex;
}
```

***

#### SettlementSig

Used during settlement to aggregate quote settlement data and overall uPnl information.

* **quotesSettlementsData:** An array of `QuoteSettlementData` structures.
* **upnlPartyBs:** An array of uPnl values for Party Bs.
* **upnlPartyA:** The uPnl value for Party A.

```solidity
struct SettlementSig {
    bytes reqId;
    uint256 timestamp;
    QuoteSettlementData[] quotesSettlementsData;
    int256[] upnlPartyBs;
    int256 upnlPartyA;
    bytes gatewaySignature;
    SchnorrSign sigs;
}
```

***

### MuonStorage Library

The **MuonStorage** library is designed to reserve a specific storage slot for all Muon‑related configuration data. It provides a single method to access the layout and thereby the Muon settings.

#### Storage Layout

The layout is defined in a struct that holds:

* **upnlValidTime:** The duration (in seconds) during which a uPnl signature remains valid.
* **priceValidTime:** The validity period for price data.
* **priceQuantityValidTime:** (Currently unused; may be removed in a future update.)
* **muonAppId:** A unique identifier for the Muon application.
* **muonPublicKey:** The public key (of type `PublicKey`) used to verify signatures.
* **validGateway:** The address of the trusted gateway whose signatures are accepted.

```solidity
library MuonStorage {
    bytes32 internal constant MUON_STORAGE_SLOT = keccak256("diamond.standard.storage.muon");

    struct Layout {
        uint256 upnlValidTime;
        uint256 priceValidTime;
        uint256 priceQuantityValidTime; // UNUSED: Should be deleted later
        uint256 muonAppId;
        PublicKey muonPublicKey;
        address validGateway;
    }

    function layout() internal pure returns (Layout storage l) {
        bytes32 slot = MUON_STORAGE_SLOT;
        assembly {
            l.slot := slot
        }
    }
}
```

[^1]: