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, application 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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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
        }
    }
}