Diamond proxy patterns for smart contract wallets: facets, selectors, and safety

Diamond proxies route calls to facets while preserving storage. Learn selectors, loupe views, and safe upgrades for IBEx smart contract wallet programs.

5 min read

Who this is for

  • Solidity architects
  • Wallet protocol engineers
  • Auditors reviewing upgradeability

Pros / cons

ProsCons
  • Single proxy address with unbounded modular growth
  • Clear interfaces for introspection when implemented carefully
  • Gas amortization versus many discrete upgrades
  • Storage layout collisions are catastrophic if disciplines slip
  • Complexity raises audit surface and developer onboarding cost
  • Misconfigured cuts can brick wallets or strand user funds

Key takeaways

  • Treat storage namespaces as contractual invariants
  • Automate selector collision checks in CI
  • Stage upgrades behind timelocks and monitoring

Diamond anatomy: proxy, facets, and delegatecall dispatch

This section explains diamond anatomy: proxy, facets, and delegatecall dispatch in the context of scw-proxy-patterns-diamond for teams shipping wallet infrastructure with IBEx Network. Architects should read it alongside threat models for phishing, supply chain compromise, and operational key handling. Engineering leads scrutinize how fallback routing maps selectors to implementation code because small mistakes become user-visible loss events or stuck funds. Documentation, tests, and signer policies must reflect the same assumptions the UI promises. Engineering leads scrutinize why delegatecall preserves proxy storage context because small mistakes become user-visible loss events or stuck funds. Documentation, tests, and signer policies must reflect the same assumptions the UI promises. Engineering leads scrutinize common diamond base contracts and their assumptions because small mistakes become user-visible loss events or stuck funds. Documentation, tests, and signer policies must reflect the same assumptions the UI promises. Standards evolve, but the underlying requirement remains honest mapping between user intent, displayed previews, and the bytes that reach the network. Use staged rollouts, canary cohorts, and synthetic signing exercises to validate changes before they reach your entire base. Maintain a living multi-chain matrix covering networks, allowed assets, bridge providers, gas sponsorship rules, and graceful degradation paths when mempools congest. Support and on-call engineers should rehearse failover using the same document. Public roadmaps that label work-in-progress chains honestly protect trust better than silent partial support. Train product, support, and compliance staff continuously on phishing, malicious signing prompts, and recovery social engineering. Internal playbooks for escalation when a user reports drained funds or stuck transactions reduce harmful improvisation. Prepared communications outperform ad-hoc threads during stressful incidents.

Facet cuts: add, replace, remove operations

This section explains facet cuts: add, replace, remove operations in the context of scw-proxy-patterns-diamond for teams shipping wallet infrastructure with IBEx Network. Architects should read it alongside threat models for phishing, supply chain compromise, and operational key handling. Engineering leads scrutinize atomicity expectations during multi-facet migrations because small mistakes become user-visible loss events or stuck funds. Documentation, tests, and signer policies must reflect the same assumptions the UI promises. Engineering leads scrutinize rollback strategies when a cut fails mid-batch because small mistakes become user-visible loss events or stuck funds. Documentation, tests, and signer policies must reflect the same assumptions the UI promises. Engineering leads scrutinize governance actors authorized to execute cuts because small mistakes become user-visible loss events or stuck funds. Documentation, tests, and signer policies must reflect the same assumptions the UI promises. Standards evolve, but the underlying requirement remains honest mapping between user intent, displayed previews, and the bytes that reach the network. Use staged rollouts, canary cohorts, and synthetic signing exercises to validate changes before they reach your entire base. Train product, support, and compliance staff continuously on phishing, malicious signing prompts, and recovery social engineering. Internal playbooks for escalation when a user reports drained funds or stuck transactions reduce harmful improvisation. Prepared communications outperform ad-hoc threads during stressful incidents. When integrations touch DeFi liquidity, document stablecoin issuers, oracle dependencies, and smart contract counterparties so risk models match user-facing copy. Advanced users appreciate transparency while newcomers avoid magical thinking about yields. Stress scenarios become testable instead of purely narrative.

Storage discipline: Diamond storage, ERC-7201, and pitfalls

This section explains storage discipline: diamond storage, erc-7201, and pitfalls in the context of scw-proxy-patterns-diamond for teams shipping wallet infrastructure with IBEx Network. Architects should read it alongside threat models for phishing, supply chain compromise, and operational key handling. Engineering leads scrutinize avoiding slot collisions between facets because small mistakes become user-visible loss events or stuck funds. Documentation, tests, and signer policies must reflect the same assumptions the UI promises. Engineering leads scrutinize documenting pointer variables and layout migrations because small mistakes become user-visible loss events or stuck funds. Documentation, tests, and signer policies must reflect the same assumptions the UI promises. Engineering leads scrutinize testing with differential storage snapshots because small mistakes become user-visible loss events or stuck funds. Documentation, tests, and signer policies must reflect the same assumptions the UI promises. Standards evolve, but the underlying requirement remains honest mapping between user intent, displayed previews, and the bytes that reach the network. Use staged rollouts, canary cohorts, and synthetic signing exercises to validate changes before they reach your entire base. When integrations touch DeFi liquidity, document stablecoin issuers, oracle dependencies, and smart contract counterparties so risk models match user-facing copy. Advanced users appreciate transparency while newcomers avoid magical thinking about yields. Stress scenarios become testable instead of purely narrative. For fiat on- and off-ramps, align marketing copy, contractual SLAs, and measured latency distributions. Funnel metrics for KYC should be shared with compliance so local optimizations do not create control gaps. Smooth resume flows after user interruption often move conversion more than marginal UI polish alone.

Wallet-specific concerns: authorization, modules, and user assets

This section explains wallet-specific concerns: authorization, modules, and user assets in the context of scw-proxy-patterns-diamond for teams shipping wallet infrastructure with IBEx Network. Architects should read it alongside threat models for phishing, supply chain compromise, and operational key handling. Engineering leads scrutinize ensuring upgrades cannot steal balances in a single transaction because small mistakes become user-visible loss events or stuck funds. Documentation, tests, and signer policies must reflect the same assumptions the UI promises. Engineering leads scrutinize pausing patterns versus immutable user expectations because small mistakes become user-visible loss events or stuck funds. Documentation, tests, and signer policies must reflect the same assumptions the UI promises. Engineering leads scrutinize eventing and indexers for transparency because small mistakes become user-visible loss events or stuck funds. Documentation, tests, and signer policies must reflect the same assumptions the UI promises. Standards evolve, but the underlying requirement remains honest mapping between user intent, displayed previews, and the bytes that reach the network. Use staged rollouts, canary cohorts, and synthetic signing exercises to validate changes before they reach your entire base. For fiat on- and off-ramps, align marketing copy, contractual SLAs, and measured latency distributions. Funnel metrics for KYC should be shared with compliance so local optimizations do not create control gaps. Smooth resume flows after user interruption often move conversion more than marginal UI polish alone. Smart accounts and ERC-4337 infrastructure shift complexity into bundlers, paymasters, and validation logic: monitor them with the same rigor as core APIs. Budget gas sponsorship explicitly and cap exposure per cohort to prevent abuse from consuming margins. Dashboards that split organic usage from subsidized traffic keep finance aligned with growth.

Frequently asked questions

Is a diamond always upgradeable?

Usually, but teams can freeze ownership or remove upgrade paths. The default pattern is powerful; governance must match user promises.

How do audits differ from transparent proxies?

Auditors trace selector tables, facet boundaries, and storage namespaces. Expect more time on integration tests across facets.

Can users verify which facet handles a call?

Loupe functions and published deployment manifests should make this inspectable. Wallets can surface facet addresses for advanced users.