Imported from okxlabs/Web3-DEX-EVM-PMM (.claude/skills/pmm-settle/SKILL.md). Install upstream with npx skills add okxlabs/Web3-DEX-EVM-PMM --skill pmm-settle. Copyright stays with the author.

Skill: PMM Settlement Contract Integration

OKX Labs PMM (Private Market Maker) RFQ Settlement Protocol integration guide.

Repository

https://github.com/okxlabs/Web3-DEX-EVM-PMM

Architecture Overview

Core Contracts

Deployment Addresses

See DEPLOYMENT.md for full V1/V2/V3 address list.

V3 PmmProtocol (Current):

V3 PmmAdaptor (Current):

V2 PmmProtocol:

V2 PmmAdaptor:

V1 PmmProtocol:

Permit2 (all chains): 0x000000000022D473030F116dDEE9F6B43aC78BA3

OrderRFQ Struct

struct OrderRFQ {
    uint256 rfqId;            // 64-bit ID for replay protection (bitmap invalidation)
    uint256 expiry;           // Unix timestamp; block.timestamp must be <= expiry
    address makerAsset;       // Token sent by maker
    address takerAsset;       // Token sent by taker
    address makerAddress;     // Signer and fund owner
    uint256 makerAmount;      // Quoted maker size
    uint256 takerAmount;      // Quoted taker size
    bool usePermit2;          // Toggle Permit2 on maker leg
    uint256 confidenceT;      // Unix timestamp: slippage starts after this (0 = disabled)
    uint256 confidenceWeight; // Reduction rate per second in 1e6 units (0 = disabled)
    uint256 confidenceCap;    // Max cumulative reduction in 1e6 units (max 50000 = 5%, 0 = disabled)
    bytes permit2Signature;   // Inline Permit2 signature (65 bytes if present)
    bytes32 permit2Witness;   // Packed witness hash for Permit2
    string permit2WitnessType;// Canonical witness type string for Permit2
}

EIP-712 Signing

Domain

// Source of truth: PmmProtocol.sol lines 58-59
const domain = {
  name: "OKX Labs PMM Protocol",   // PmmProtocol.sol:58
  version: "1.1",                   // PmmProtocol.sol:59
  chainId: <chainId>,
  verifyingContract: <PmmProtocol address>
};

Script status (updated 2026-03-11):

• signOrderRFQ.js — FIXED: version corrected to "1.1"
• verifyDigest.js — removed from repo (was outdated: wrong domain name, missing confidence fields)

OrderRFQ Typehash

OrderRFQ(uint256 rfqId,uint256 expiry,address makerAsset,address takerAsset,address makerAddress,uint256 makerAmount,uint256 takerAmount,bool usePermit2,uint256 confidenceT,uint256 confidenceWeight,uint256 confidenceCap,bytes permit2Signature,bytes32 permit2Witness,string permit2WitnessType)

IMPORTANT: bytes fields are hashed with keccak256(), string fields are hashed with keccak256(toUtf8Bytes()) before encoding.

Struct Hash Encoding

const structHash = keccak256(abi.encode(
  ORDER_RFQ_TYPEHASH,
  order.rfqId,
  order.expiry,
  order.makerAsset,
  order.takerAsset,
  order.makerAddress,
  order.makerAmount,
  order.takerAmount,
  order.usePermit2,
  order.confidenceT,
  order.confidenceWeight,
  order.confidenceCap,
  keccak256(order.permit2Signature),  // bytes -> keccak256
  order.permit2Witness,                // bytes32 as-is
  keccak256(toUtf8Bytes(order.permit2WitnessType))  // string -> keccak256
));

Digest

digest = keccak256(concat(["0x1901", domainSeparator, structHash]));

Signature Format

// Sign raw digest (NO Ethereum message prefix)
const sig = wallet.signingKey.sign(digest);
// Pack as r + s + v (65 bytes)
const signature = concat([sig.r, sig.s, toBeHex(sig.v, 1)]);

Reference implementation: script/signOrderRFQ.js

Permit2 Integration

Overview

The maker leg supports two Permit2 modes when order.usePermit2 = true:

Mode 1: Allowance-based (no inline signature)

• Maker pre-approves Permit2 contract for the maker asset
• permit2Signature is empty ("0x" or bytes(""))
• Contract calls safeTransferFromPermit2(makerAsset, maker, receiver, makerAmount)
• Amount capped at uint160.max

Mode 2: Signature-based (inline Permit2 signature)

• permit2Signature contains a 65-byte Permit2 signature
• Uses order.rfqId as Permit2 nonce
• Uses order.expiry as Permit2 deadline

Without Witness

When permit2WitnessType is empty:

// Permit2 PermitTransferFrom
const permit = {
  permitted: { token: order.makerAsset, amount: order.makerAmount },
  nonce: order.rfqId,
  deadline: order.expiry
};
// Contract calls: permit2.permitTransferFrom(permit, transferDetails, maker, signature)

With Witness (recommended for production)

When permit2WitnessType is non-empty:

// 1. Define witness struct (e.g., Consideration)
const CONSIDERATION_TYPEHASH = keccak256(toUtf8Bytes(
  "Consideration(address token,uint256 amount,address counterparty)"
));

// 2. Calculate witness hash
const witnessHash = keccak256(abi.encode(
  CONSIDERATION_TYPEHASH,
  consideration.token,     // e.g., takerAsset
  consideration.amount,    // e.g., takerAmount
  consideration.counterparty  // e.g., taker address
));

// 3. Set witness type string (MUST follow Permit2 EIP-712 format)
const witnessTypeString =
  "Consideration witness)Consideration(address token,uint256 amount,address counterparty)TokenPermissions(address token,uint256 amount)";

// 4. Sign Permit2 with witness
const PERMIT_WITNESS_TRANSFER_FROM_TYPEHASH = keccak256(toUtf8Bytes(
  `PermitWitnessTransferFrom(TokenPermissions permitted,address spender,uint256 nonce,uint256 deadline,${witnessTypeString}`
));

const tokenPermissionsHash = keccak256(abi.encode(
  TOKEN_PERMISSIONS_TYPEHASH,
  permit.permitted.token,
  permit.permitted.amount
));

const structHash = keccak256(abi.encode(
  PERMIT_WITNESS_TRANSFER_FROM_TYPEHASH,
  tokenPermissionsHash,
  spender,           // PmmProtocol address
  permit.nonce,      // order.rfqId
  permit.deadline,   // order.expiry
  witnessHash        // keccak256 of encoded witness data
));

const digest = keccak256(concat(["0x1901", permit2DomainSeparator, structHash]));
const sig = wallet.signingKey.sign(digest);
const permit2Signature = concat([sig.r, sig.s, toBeHex(sig.v, 1)]);

// 5. Populate order fields
order.permit2Signature = permit2Signature;
order.permit2Witness = witnessHash;
order.permit2WitnessType = witnessTypeString;

Contract calls: permit2.permitWitnessTransferFrom(permit, transferDetails, maker, witness, witnessTypeString, signature)

Permit2 Domain Separator

The Permit2 contract has its own EIP-712 domain (separate from PmmProtocol's domain).

IMPORTANT: Permit2's EIP712Domain has only 3 fields (NO version), unlike PmmProtocol's 4-field domain:

// Permit2 domain type (note: NO version field!)
const PERMIT2_DOMAIN_TYPE = "EIP712Domain(string name,uint256 chainId,address verifyingContract)";

// Compute manually (from verifyDigest.js:150-163):
const permit2DomainSeparator = keccak256(abi.encode(
  keccak256(toUtf8Bytes(PERMIT2_DOMAIN_TYPE)),
  keccak256(toUtf8Bytes("Permit2")),
  chainId,
  "0x000000000022D473030F116dDEE9F6B43aC78BA3"
));

// Or read from contract:
const permit2DomainSeparator = await permit2Contract.DOMAIN_SEPARATOR();

Critical Notes on Permit2 Signing

1. Two separate signatures required: The order needs an EIP-712 OrderRFQ signature (signed against PmmProtocol domain), AND a Permit2 signature (signed against Permit2 domain). These are different digests with different domain separators.
2. Nonce = rfqId: Permit2 uses order.rfqId as the nonce. Each rfqId can only be used once.
3. Deadline = expiry: Permit2 deadline is set to order.expiry.
4. Spender = PmmProtocol: The spender in Permit2 is the PmmProtocol contract address.
5. Witness type string format: Must exactly follow Permit2's EIP-712 type concatenation rules. The string starts with the member name (witness)) then lists all referenced types alphabetically.
6. Signature format: Both signatures are 65 bytes: r (32) + s (32) + v (1).

Time-Slippage (Confidence) Mechanism

Unit System

Parts-per-million (1e6 = 100%)

Conversion from bps

confidenceWeight = bps_per_second * 100
confidenceCap    = bps_cap * 100

Example: 0.75 bps/s rate, 12 bps cap:

• confidenceWeight = 75 (0.75 * 100)
• confidenceCap = 1200 (12 * 100)

Formula

if block.timestamp > confidenceT && all three params != 0:
  timeDiff            = block.timestamp - confidenceT
  cutdownPercentageX6 = min(timeDiff * confidenceWeight, confidenceCap)
  adjustedMakerAmount = makerAmount - makerAmount * cutdownPercentageX6 / 1e6

Rules

• Any param = 0 disables slippage entirely
• Only makerAmount is reduced; takerAmount unchanged
• Settlement limit (60%) checked BEFORE confidence reduction
• confidenceCap > 50000 reverts with RFQ_ConfidenceCapExceeded

Fill Flow (flagsAndAmount)

Bit Flags

Fill Functions

// Fill to msg.sender
fillOrderRFQ(OrderRFQ order, bytes signature, uint256 flagsAndAmount)

// Fill to specific target
fillOrderRFQTo(OrderRFQ order, bytes signature, uint256 flagsAndAmount, address target)

// Execute ERC20 permit before filling
fillOrderRFQToWithPermit(OrderRFQ order, bytes signature, uint256 flagsAndAmount, address target, bytes permit)

// Compact signature (r, vs) format
fillOrderRFQCompact(OrderRFQ order, uint256 r, uint256 vs, uint256 flagsAndAmount)

Settlement Limit

Both sides must be >= 60% of quoted amounts:

makerAmount >= order.makerAmount * 6000 / 10000
takerAmount >= order.takerAmount * 6000 / 10000

Error Reference

Event

event OrderFilledRFQ(
    uint256 indexed rfqId,
    uint256 expiry,
    address indexed makerAsset,
    address indexed takerAsset,
    address makerAddress,
    uint256 expectedMakerAmount,
    uint256 expectedTakerAmount,
    uint256 filledMakerAmount,
    uint256 filledTakerAmount,
    bool usePermit2,
    bytes permit2Signature,
    bytes32 permit2Witness,
    string permit2WitnessType
);

Order Scenarios (from testSignOrder.js)

Scenario 1: No Permit2

{ usePermit2: false, permit2Signature: "0x",
  permit2Witness: "0x0000...0000", permit2WitnessType: "" }

Scenario 2: Permit2, no witness (allowance-based)

{ usePermit2: true, permit2Signature: "0x",
  permit2Witness: "0x0000...0000", permit2WitnessType: "" }

Scenario 3: Permit2 + ExampleWitness

const WITNESS_TYPE_STRING = "ExampleWitness witness)ExampleWitness(address user)TokenPermissions(address token,uint256 amount)";
{ usePermit2: true,
  permit2Signature: signPermit2WithWitness({...witness: calculateWitness({user: MAKER_ADDRESS}), witnessTypeString: WITNESS_TYPE_STRING...}),
  permit2Witness: calculateWitness({user: MAKER_ADDRESS}),
  permit2WitnessType: WITNESS_TYPE_STRING }

Scenario 4: Permit2 + Consideration witness (production)

const CONSIDERATION_TYPE_STRING = "Consideration witness)Consideration(address token,uint256 amount,address counterparty)TokenPermissions(address token,uint256 amount)";
const CONSIDERATION = { token: MAKER_ASSET, amount: MAKER_AMOUNT, counterparty: TAKER_ADDRESS };
{ usePermit2: true,
  permit2Signature: signPermit2WithWitness({...witness: calculateWitnessConsideration(CONSIDERATION), witnessTypeString: CONSIDERATION_TYPE_STRING...}),
  permit2Witness: calculateWitnessConsideration(CONSIDERATION),
  permit2WitnessType: CONSIDERATION_TYPE_STRING }

Quick Integration Checklist

1. Construct OrderRFQ struct with all 14 fields
2. If using Permit2 with inline signature: a. Compute witness hash (if using witness mode) b. Sign Permit2 PermitTransferFrom against Permit2 domain (3-field, NO version) c. Set permit2Signature, permit2Witness, permit2WitnessType on order
3. Sign OrderRFQ with maker's private key against PmmProtocol domain (4-field, version "1.1")
   • NOTE: OrderRFQ signature covers the Permit2 signature bytes (hashed), so Permit2 must be signed FIRST
4. Call fillOrderRFQTo() with order, OrderRFQ signature, flagsAndAmount, target
5. Handle events and errors appropriately

Reference Files

• Order signing: script/signOrderRFQ.js (WARNING: version "1.0" should be "1.1")
• Sign test vectors: script/testSignOrder.js (4 scenarios: no-permit2, permit2-no-witness, ExampleWitness, Consideration)
• Digest verification: script/verifyDigest.js (WARNING: outdated — wrong domain name, missing confidence fields)
• Core contract: src/PmmProtocol.sol
• Order struct: src/OrderRFQLib.sol
• Tests: test/PmmProtocol.t.sol, test/PmmProtocolTimeSlippage.t.sol, test/PmmProtocolPermitWitnessFork.t.sol