Scope note
This page is the public lookup surface for DerivaDEX’s diamond-oriented contract composition. It covers facet families, selector lookup rules, event families, and gas-sensitive interaction categories that matter to public integrators and governance participants. It does not publish a complete per-selector ABI manual for every deployment or a timeless gas-cost table.Diamond lookup surfaces
| Surface | What it tells you |
|---|---|
facetAddresses() | which facet implementation addresses are currently installed behind the diamond |
facetFunctionSelectors(address) | which selectors are currently routed to a specific facet |
facetAddress(bytes4) | which facet currently owns one selector |
diamondCut(...) | the upgrade entrypoint that adds, replaces, or removes selectors through governance-routed contract changes |
Repo-carried lookup carriers
| Need | Repo carrier |
|---|---|
| loupe and cut interfaces | v2/packages/protocol-harness/contracts/src/diamond/IDiamondLoupe.sol, v2/packages/protocol-harness/contracts/src/diamond/IDiamondCut.sol |
| current loupe implementation | v2/packages/protocol-harness/contracts/src/diamond/DiamondFacet.sol |
| governance events and selectors | v2/packages/protocol-harness/contracts/src/facets/interfaces/IGovernance.sol, v2/packages/protocol-harness/contracts/src/facets/Governance.sol, v2/packages/protocol-harness/contracts/src/facets/GovernanceDip12.sol |
| token delegation events | v2/packages/protocol-harness/contracts/src/tokens/DDX.sol |
| facet family inventory | v2/packages/protocol-harness/contracts/src/facets/*.sol, v2/packages/protocol-harness/contracts/src/facets/interfaces/*.sol |
Publicly relevant facet families
| Facet family | Public role | Public lookup rule |
|---|---|---|
| Governance | proposal creation, queue, execute, quorum, thresholds | bind governance ABI calls to the diamond address |
| GovernanceDip12 | extended voting mechanics such as voting-cap enforcement and vote casting | treat it as a governance extension behind the same diamond |
| Registration | trader admission and registration state | use for public onboarding-state interpretation, not private operator workflow guesses |
| Custodian | custody- and operator-adjacent control surfaces | relevant to public boundary explanation, not a public operating manual |
| Banner | sanctions or denial-style status changes | public readers may encounter the effect, but not every internal review step |
| Pause | emergency or governed pause state | relevant for fast-path governance and safety interpretation |
| Checkpoint | settlement and checkpoint anchoring | relevant for settlement/finality interpretation |
| Collateral | USDC collateral deposit and withdrawal surfaces | relevant for on-chain collateral interactions |
| Stake | DDX staking and governance-linked stake flows | relevant for governance participation and staking state |
| Specs | market and risk parameter storage | relevant for governed product/risk changes |
| InsuranceFund / FundedInsuranceFund | solvency backstop and funded insurance behavior | relevant for liquidation and backstop interpretation |
| Trader | trader-facing contract state coupled to the platform | relevant when reads or writes are explicitly on-chain |
Selector-routing rules
| Rule | Public contract |
|---|---|
| Call target | protocol-facing reads and writes target the diamond proxy address, not the facet implementation address |
| ABI choice | use the facet ABI or interface that defines the function you need, but bind it to the diamond address |
| Selector ownership | use facetAddress(bytes4) when you need to confirm which facet currently owns one function selector |
| Facet inventory | use facetAddresses() plus facetFunctionSelectors(address) when you need to inspect current installation and selector coverage |
| Upgrade sensitivity | selector ownership can change after diamondCut, so selector availability is deployment- and upgrade-dependent rather than timeless |
Public selector and event lookup sequence
| Question | First lookup | Follow-up |
|---|---|---|
| which facet owns one function today | facetAddress(bytes4) | bind the relevant interface to the diamond proxy address |
| which selectors one facet exposes | facetFunctionSelectors(address) | compare with the facet interface or source file in the repo carrier |
| whether a governance upgrade happened | DiamondCut plus governance execution events | match the emitted action set to the proposal and queue or execute transaction evidence |
| whether vote delegation or vote weight changed | DelegateChanged / DelegateVotesChanged | verify against DDX token events and the relevant governance action context |
Diamond cut validation rules
| Case | Verified rule |
|---|---|
| add selectors | requires a non-zero facet address and a non-empty selector list |
| remove selectors | requires the zero address as the facet target |
| add duplicate selector | reverts |
| replace with same facet/function | reverts |
| remove nonexistent selector | reverts |
| loupe accuracy | loupe selector views should match the currently installed selector set after successful upgrades |
Public event families
| Event | Why public readers care |
|---|---|
DiamondCut | proves a selector-routing upgrade happened |
OwnershipTransferred | proves admin/ownership transition on ownership-bearing contract surfaces |
ProposalCreated | proves the on-chain proposal was created with a specific action set |
VoteCast | proves a wallet cast a vote with a recorded weight |
ProposalQueued | proves a proposal entered the execution queue and has an ETA |
ProposalExecuted | proves the proposal completed execution |
QueueTransaction | proves a specific proposal action was queued |
ExecuteTransaction | proves a specific proposal action executed |
DelegateChanged | proves DDX voting power delegation changed |
DelegateVotesChanged | proves a delegate’s vote count changed |
Gas-sensitive interaction categories
| Category | Why gas behavior varies |
|---|---|
| deposits and withdrawals | token transfer cost, allowance state, and settlement-adjacent bookkeeping vary by token state and network conditions |
| delegation and voting | signed-message use, vote-accounting updates, and governance state transitions change execution cost |
| proposal queue and execute | queued action count, calldata size, and time-based execution path affect cost |
| diamond upgrades | selector count, initialization calldata, and facet install or replacement shape cost materially |
| checkpoint- and settlement-adjacent actions | network state and state-transition breadth affect cost and latency |