LibMuon (0.8.5)

The LibMuon library provides the cryptographic functions that verify signed data for SYMM contracts: uPNL calculations, price data, liquidation events, and settlement data. It relies on trusted Muon signatures (via a TSS mechanism) and gateway signature checks to confirm the data is authentic and unmodified.

---

Core Functions

getChainId

Returns the chain ID of the network the contract runs on. Used to tie signed data to the correct network.

function getChainId() internal view returns (uint256 id) {
    assembly {
        id := chainid()
    }
}

---

verifyTSSAndGateway

Runs two signature checks:

1. TSS verification: calls LibMuonV04ClientBase.muonVerify to confirm the data hash is signed by the Muon public key.

2. Gateway verification: converts the hash to an Ethereum signed message hash and recovers the signer address, which must match the validGateway address stored in MuonStorage.

Parameters:

• hash: Hash of the data to verify.

• sign: SchnorrSign structure holding the TSS signature.

• gatewaySignature: The gateway signature as a byte array.

function verifyTSSAndGateway(
    bytes32 hash,
    SchnorrSign memory sign,
    bytes memory gatewaySignature
) internal view {
    bool verified = LibMuonV04ClientBase.muonVerify(uint256(hash), sign, MuonStorage.layout().muonPublicKey);
    require(verified, "LibMuon: TSS not verified");

    hash = hash.toEthSignedMessageHash();
    address gatewaySignatureSigner = hash.recover(gatewaySignature);
    require(gatewaySignatureSigner == MuonStorage.layout().validGateway, "LibMuon: Gateway is not valid");
}

---

verifyPartyBUpnl

Verifies PartyB's uPNL data. Checks the signature has not expired, builds a hash from key parameters (PartyB's nonce, the uPNL value, the current chain ID), then calls verifyTSSAndGateway.

Parameters:

• upnlSig: SingleUpnlSig structure holding uPNL data and signature details.

• partyB: PartyB address.

• partyA: PartyA address.

function verifyPartyBUpnl(SingleUpnlSig memory upnlSig, address partyB, address partyA) internal view {
    MuonStorage.Layout storage muonLayout = MuonStorage.layout();
    require(block.timestamp <= upnlSig.timestamp + muonLayout.upnlValidTime, "LibMuon: Expired signature");
    bytes32 hash = keccak256(
        abi.encodePacked(
            muonLayout.muonAppId,
            upnlSig.reqId,
            address(this),
            partyB,
            partyA,
            AccountStorage.layout().partyBNonces[partyB][partyA],
            upnlSig.upnl,
            upnlSig.timestamp,
            getChainId()
        )
    );
    verifyTSSAndGateway(hash, upnlSig.sigs, upnlSig.gatewaySignature);
}

---

LibMuonAccount

verifyPartyAUpnl

Verifies PartyA's uPNL data. Builds a hash from PartyA's nonce and uPNL value, then validates it through TSS and gateway verification.

Parameters:

• upnlSig: SingleUpnlSig structure.

• partyA: PartyA address.

function verifyPartyAUpnl(SingleUpnlSig memory upnlSig, address partyA) internal view {
    MuonStorage.Layout storage muonLayout = MuonStorage.layout();
    require(block.timestamp <= upnlSig.timestamp + muonLayout.upnlValidTime, "LibMuon: Expired signature");
    bytes32 hash = keccak256(
        abi.encodePacked(
            muonLayout.muonAppId,
            upnlSig.reqId,
            address(this),
            partyA,
            AccountStorage.layout().partyANonces[partyA],
            upnlSig.upnl,
            upnlSig.timestamp,
            LibMuon.getChainId()
        )
    );
    LibMuon.verifyTSSAndGateway(hash, upnlSig.sigs, upnlSig.gatewaySignature);
}

verifyPartyBUpnl (LibMuonAccount)

Delegates to LibMuon's verifyPartyBUpnl to validate PartyB's uPNL data.

function verifyPartyBUpnl(SingleUpnlSig memory upnlSig, address partyB, address partyA) internal view {
    LibMuon.verifyPartyBUpnl(upnlSig, partyB, partyA);
}

---

LibMuonForceActions

verifyHighLowPrice

Verifies that the high, low, current, and average price data in a HighLowPriceSig are authentic and within the valid time window. Builds a hash from nonces and market price data, then verifies the signature.

Parameters:

• sig: HighLowPriceSig structure.

• partyB: PartyB address.

• partyA: PartyA address.

• symbolId: Trading symbol identifier.

function verifyHighLowPrice(HighLowPriceSig memory sig, address partyB, address partyA, uint256 symbolId) internal view {
    MuonStorage.Layout storage muonLayout = MuonStorage.layout();
    require(block.timestamp <= sig.timestamp + muonLayout.upnlValidTime, "LibMuon: Expired signature");
    bytes32 hash = keccak256(
        abi.encodePacked(
            muonLayout.muonAppId,
            sig.reqId,
            address(this),
            partyB,
            partyA,
            AccountStorage.layout().partyBNonces[partyB][partyA],
            AccountStorage.layout().partyANonces[partyA],
            sig.upnlPartyB,
            sig.upnlPartyA,
            symbolId,
            sig.currentPrice,
            sig.startTime,
            sig.endTime,
            sig.lowest,
            sig.highest,
            sig.averagePrice,
            sig.timestamp,
            LibMuon.getChainId()
        )
    );
    LibMuon.verifyTSSAndGateway(hash, sig.sigs, sig.gatewaySignature);
}

---

LibMuonFundingRate

verifyPairUpnl

Verifies the pair uPNL data used in funding rate calculations. Builds a hash from both PartyB and PartyA uPNL values and their nonces, then verifies the signature.

Parameters:

• upnlSig: PairUpnlSig structure.

• partyB: PartyB address.

• partyA: PartyA address.

function verifyPairUpnl(PairUpnlSig memory upnlSig, address partyB, address partyA) internal view {
    MuonStorage.Layout storage muonLayout = MuonStorage.layout();a
    require(block.timestamp <= upnlSig.timestamp + muonLayout.upnlValidTime, "LibMuon: Expired signature");
    bytes32 hash = keccak256(
        abi.encodePacked(
            muonLayout.muonAppId,
            upnlSig.reqId,
            address(this),
            partyB,
            partyA,
            AccountStorage.layout().partyBNonces[partyB][partyA],
            AccountStorage.layout().partyANonces[partyA],
            upnlSig.upnlPartyB,
            upnlSig.upnlPartyA,
            upnlSig.timestamp,
            LibMuon.getChainId()
        )
    );
    LibMuon.verifyTSSAndGateway(hash, upnlSig.sigs, upnlSig.gatewaySignature);
}

---

LibMuonLiquidation

verifyLiquidationSig

Validates the liquidation signal for PartyA. Requires the prices and symbolIds arrays to have matching lengths, builds a hash from key liquidation parameters (liquidation ID, uPNL values, nonce), then verifies it.

Parameters:

• liquidationSig: LiquidationSig structure.

• partyA: PartyA address.

function verifyLiquidationSig(LiquidationSig memory liquidationSig, address partyA) internal view {
    MuonStorage.Layout storage muonLayout = MuonStorage.layout();
    require(liquidationSig.prices.length == liquidationSig.symbolIds.length, "LibMuon: Invalid length");
    bytes32 hash = keccak256(
        abi.encodePacked(
            muonLayout.muonAppId,
            liquidationSig.reqId,
            liquidationSig.liquidationId,
            address(this),
            "verifyLiquidationSig",
            partyA,
            AccountStorage.layout().partyANonces[partyA],
            liquidationSig.upnl,
            liquidationSig.totalUnrealizedLoss,
            liquidationSig.symbolIds,
            liquidationSig.prices,
            liquidationSig.timestamp,
            LibMuon.getChainId()
        )
    );
    LibMuon.verifyTSSAndGateway(hash, liquidationSig.sigs, liquidationSig.gatewaySignature);
}

verifyDeferredLiquidationSig

Verifies a deferred liquidation signature. Includes extra parameters in the hash (liquidation block number, timestamp, allocated balance) so the deferred liquidation data is validated and signed.

Parameters:

• liquidationSig: DeferredLiquidationSig structure.

• partyA: PartyA address.

function verifyDeferredLiquidationSig(DeferredLiquidationSig memory liquidationSig, address partyA) internal view {
    MuonStorage.Layout storage muonLayout = MuonStorage.layout();
    require(liquidationSig.prices.length == liquidationSig.symbolIds.length, "LibMuon: Invalid length");
    bytes32 hash = keccak256(
        abi.encodePacked(
            muonLayout.muonAppId,
            liquidationSig.reqId,
            liquidationSig.liquidationId,
            address(this),
            "verifyDeferredLiquidationSig",
            partyA,
            AccountStorage.layout().partyANonces[partyA],
            liquidationSig.upnl,
            liquidationSig.totalUnrealizedLoss,
            liquidationSig.symbolIds,
            liquidationSig.prices,
            liquidationSig.timestamp,
            liquidationSig.liquidationBlockNumber,
            liquidationSig.liquidationTimestamp,
            liquidationSig.liquidationAllocatedBalance,
            LibMuon.getChainId()
        )
    );
    LibMuon.verifyTSSAndGateway(hash, liquidationSig.sigs, liquidationSig.gatewaySignature);
}

verifyQuotePrices

Verifies quote price data. Requires the prices array to match the quoteIds array, builds the corresponding hash, then validates the signatures.

Parameters:

• priceSig: QuotePriceSig structure holding arrays of quote IDs and their prices.

function verifyQuotePrices(QuotePriceSig memory priceSig) internal view {
    MuonStorage.Layout storage muonLayout = MuonStorage.layout();
    require(priceSig.prices.length == priceSig.quoteIds.length, "LibMuon: Invalid length");
    bytes32 hash = keccak256(
        abi.encodePacked(
            muonLayout.muonAppId,
            priceSig.reqId,
            address(this),
            priceSig.quoteIds,
            priceSig.prices,
            priceSig.timestamp,
            LibMuon.getChainId()
        )
    );
    LibMuon.verifyTSSAndGateway(hash, priceSig.sigs, priceSig.gatewaySignature);
}

---

LibMuonPartyB

verifyPairUpnlAndPrice

Verifies combined uPNL and price data for PartyB and PartyA on a given symbol. Builds a hash from the nonces, uPNL values, and price, then validates the signatures.

Parameters:

• upnlSig: PairUpnlAndPriceSig structure.

• partyB: PartyB address.

• partyA: PartyA address.

• symbolId: Trading symbol identifier.

function verifyPairUpnlAndPrice(
    PairUpnlAndPriceSig memory upnlSig,
    address partyB,
    address partyA,
    uint256 symbolId
) internal view {
    MuonStorage.Layout storage muonLayout = MuonStorage.layout();
    require(block.timestamp <= upnlSig.timestamp + muonLayout.upnlValidTime, "LibMuon: Expired signature");
    bytes32 hash = keccak256(
        abi.encodePacked(
            muonLayout.muonAppId,
            upnlSig.reqId,
            address(this),
            partyB,
            partyA,
            AccountStorage.layout().partyBNonces[partyB][partyA],
            AccountStorage.layout().partyANonces[partyA],
            upnlSig.upnlPartyB,
            upnlSig.upnlPartyA,
            symbolId,
            upnlSig.price,
            upnlSig.timestamp,
            LibMuon.getChainId()
        )
    );
    LibMuon.verifyTSSAndGateway(hash, upnlSig.sigs, upnlSig.gatewaySignature);
}

verifyPartyBUpnl (LibMuonPartyB)

Delegates to LibMuon's verifyPartyBUpnl to verify PartyB's uPNL data.

function verifyPartyBUpnl(
    SingleUpnlSig memory upnlSig,
    address partyB,
    address partyA
) internal view {
    LibMuon.verifyPartyBUpnl(upnlSig, partyB, partyA);
}

---

LibMuonSettlement

verifySettlement

Validates settlement data for a set of quotes. Builds a hash aggregating settlement details (quote settlement data, nonces, uPNL values), then verifies the signature through the TSS and gateway checks.

Parameters:

• settleSig: SettlementSig structure containing reqId, an array of quotesSettlementsData, upnlPartyBs, upnlPartyA, timestamp, and signature data.

• partyA: PartyA address.

function verifySettlement(SettlementSig memory settleSig, address partyA) internal view {
    MuonStorage.Layout storage muonLayout = MuonStorage.layout();
    uint256 length = settleSig.quotesSettlementsData.length;
    bytes memory encodedData;
    uint256[] memory nonces = new uint256[](length);
    for (uint8 i = 0; i < length; i++) {
        nonces[i] = AccountStorage.layout().partyBNonces[QuoteStorage.layout().quotes[settleSig.quotesSettlementsData[i].quoteId].partyB][partyA];
        encodedData = abi.encodePacked(
            encodedData,
            settleSig.quotesSettlementsData[i].quoteId,
            settleSig.quotesSettlementsData[i].currentPrice,
            settleSig.quotesSettlementsData[i].partyBUpnlIndex
        );
    }
    bytes32 hash = keccak256(
        abi.encodePacked(
            muonLayout.muonAppId,
            settleSig.reqId,
            address(this),
            "verifySettlement",
            nonces,
            AccountStorage.layout().partyANonces[partyA],
            encodedData,
            settleSig.upnlPartyBs,
            settleSig.upnlPartyA,
            settleSig.timestamp,
            LibMuon.getChainId()
        )
    );
    LibMuon.verifyTSSAndGateway(hash, settleSig.sigs, settleSig.gatewaySignature);
}