Why the public docs treat contract architecture as a boundary problem
DerivaDEX exposes important on-chain contract surfaces, but not every meaningful platform behavior is best understood as a smart-contract API problem. Matching, sequencing, market-data delivery, and settlement evidence live across different layers. That is why the public docs separate:- contract addresses and on-chain roles
- API-driven market and account workflows
- governance-routed upgrade and execution boundaries
The diamond model in practical terms
DerivaDEX uses a diamond-style contract entrypoint. The practical implication for integrators is simple:- the diamond proxy address is the protocol-facing call target
- facet ABIs identify functions and selectors
- selector routing can change when upgrades change the facet composition
Why this matters to different builders
| Builder question | What the docs want you to understand |
|---|---|
| which address should I bind my interface to? | the diamond address is the stable protocol-facing call target |
| where do selectors and events come from? | facet-level ABI and selector information explain capability ownership |
| can I treat contract calls as the whole platform interface? | no; live trading, sequencing, and account updates still span REST and realtime families |
Why facet addresses are not the integration target
Facet implementation contracts are not the stable integration surface. Calling a facet address directly can bypass the storage and routing assumptions the diamond model relies on. Public docs therefore tell integrators to bind the relevant interface to the diamond address, not to a facet implementation address.Why upgrades affect client assumptions
Upgrades do not just add new functionality. They can also change selector routing, remove previously available selectors, or alter which facet owns a capability in one deployment mode versus another. This is why public docs describe upgrade boundaries and governance relevance, but do not overpromise timeless selector stability.Why the contract layer still needs governance context
Contract architecture and upgrade posture are not only technical details. They also matter to governance readers because:- upgrade authority changes what “stable integration surface” really means over time
- selector ownership and facet composition can move with governance-approved changes
- on-chain contract maps are part of the public accountability story, not just the builder story
Why contract architecture does not replace the API families
The smart-contract layer is important, but it does not replace the public REST and realtime families:- REST provides request-response discovery and initial state
- realtime provides live market and account updates
- contracts provide the on-chain surfaces for settlement, governance, token, and other environment-bound interactions
The public boundary rule
The public docs publish the contract map, the environment-targeting cautions, and the safe integration rules. They do not yet publish a complete facet-by-facet ABI manual, every event catalog, or a timeless gas-optimization reference.Sources
- Smart Contract Addresses and Core Contract Reference for environment targeting and core on-chain role mapping
- Smart Contract Facet, Selector, and Event Reference for selector and event lookup posture
- Governance Process and Public Decision Reference for the governance context around protocol change
- API Reference for the transport families that sit alongside contract interactions