DiamondProxy Standard on Soroban

[tbraun96-nomyx]

Stellar Diamond Proxy Proposal: Enabling Modular and Upgradeable Smart Contracts

Preamble

SEP: TBD
Title: Diamond Proxy Standard for Soroban
Author: Nomyx
Track: Standard
Status: Draft
Created: 2025-03-28
Updated: 2025-03-31
Version: 0.1.0
Discussion: TBD

Simple Summary

The Diamond Proxy Standard proposes a modular smart contract architecture for Soroban that enables multiple contract facets to share storage and functionality through a single entry point, allowing upgradeable contracts with improved modularity, code sharing, and domain-specific logic separation.

Dependencies

This SEP has no dependencies on other SEPs or CAPs.

Motivation

Current smart contract patterns on Soroban face several challenges:

1. Monolithic Design: Smart contracts tend to be deployed as single, large units that are difficult to maintain and upgrade.
2. Limited Upgradability: Standard upgrade patterns often require replacing the entire contract, complicating migrations and introducing security risks.
3. Isolated Storage: Each contract has its own isolated storage, making it challenging to share state across related functionality.
4. Code Duplication: Common functionality must be duplicated across contracts due to a lack of inheritance or composition mechanisms.

The Diamond Proxy Standard addresses these issues by providing a modular architecture where multiple facet contracts share a common storage layer while being accessible through a single proxy entry point. This enables granular upgrades, clean separation of concerns, and efficient shared state management.

Limitation of Current Stellar Smart Contracts	Potential Benefit of Diamond Proxy Implementation
Difficulty in managing large codebases for complex smart contracts	Enhanced modularity and organization through the use of facets
Limited mechanisms for upgrading smart contract logic without full redeployment	Simplified and controlled upgrades of specific functionalities via diamond_cut
Potential constraints on the size and complexity of individual smart contracts	Ability to build more feature-rich applications by distributing logic across multiple facets
Challenges in isolating and fixing bugs in monolithic contracts	Improved maintainability and easier debugging by focusing on individual facets

Abstract

The Diamond Proxy Standard defines a pattern for creating modular, upgradeable smart contracts on Soroban. Inspired by Ethereum's ERC-2535 (Diamond Standard) but adapted for Soroban's unique environment, this standard introduces a proxy contract that delegates calls to various facet contracts while providing a shared storage solution and standard introspection capabilities.

The key innovation is the combination of a delegation proxy with a dedicated shared storage contract that all facets can access. This architecture enables:

1. Upgrading specific facets without affecting others.
2. Sharing state between facets using standard Soroban types, without complex cross-contract calls or manual serialization.
3. Breaking down complex contract systems into manageable, domain-specific modules.
4. Maintaining a single user-facing address regardless of the underlying implementation.
5. Standard on-chain introspection of the diamond's structure using Loupe functions.

The standard includes definitions for the diamond proxy (including Loupe functions), facets, shared storage, and the factory contract responsible for deployment and initialization.

Specification

1. Core Components

1.1 DiamondProxy

The DiamondProxy is the entry point contract that users interact with. Internally, it maintains a mapping (e.g., Map<Symbol, Address>) associating function selectors with the Address of the facet contract responsible for handling them. It delegates calls to the appropriate facet based on this mapping and provides standard Loupe functions for introspection.

#[contract]
pub struct DiamondProxy;

#[contractimpl]
impl DiamondProxy {
    pub fn init(env: Env, owner: Address) -> Result<(), Error>;
    pub fn diamond_cut(env: Env, diamond_cut: Vec<FacetCut>, salt: Option<BytesN<32>>) -> Result<Vec<Address>, Error>;
    pub fn fallback(env: Env, selector: Symbol, args: Vec<Val>) -> Result<Val, Error>;

    // Loupe functions
    pub fn facet_address(env: Env, selector: Symbol) -> Option<Address>;
    pub fn facet_addresses(env: Env) -> Vec<Address>;
    pub fn facet_function_selectors(env: Env, facet: Address) -> Vec<Symbol>;
    pub fn facets(env: Env) -> Map<Address,Vec<Facet>>;
}

1.2 SharedStorageLayer

The SharedStorageLayer is a specialized contract that provides unified storage access for all facet contracts associated with a DiamondProxy. It stores data as raw Bytes internally but is accessed by facets via helper functions that handle serialization/deserialization. It segregates storage into instance, persistent, and temporary types.

#[contract]
pub struct SharedStorageLayer;

#[contractimpl]
impl SharedStorageLayer {
    pub fn init(env: Env, owner: Address) -> Result<(), Error>;
    // Instance storage operations
    pub fn get_instance_shared_storage_at(env: Env, key: Bytes) -> Option<Bytes>;
    pub fn set_instance_shared_storage_at(env: Env, key: Bytes, value: Bytes) -> Result<(), Error>;
    pub fn del_instance_shared_storage_at(env: Env, key: Bytes) -> Result<(), Error>;
    // Persistent storage operations
    pub fn get_persistent_shared_storage_at(env: Env, key: Bytes) -> Option<Bytes>;
    pub fn set_persistent_shared_storage_at(env: Env, key: Bytes, value: Bytes) -> Result<(), Error>;
    pub fn del_persistent_shared_storage_at(env: Env, key: Bytes) -> Result<(), Error>;
    // Temporary storage operations
    pub fn get_temporary_shared_storage_at(env: Env, key: Bytes) -> Option<Bytes>;
    pub fn set_temporary_shared_storage_at(env: Env, key: Bytes, value: Bytes) -> Result<(), Error>;
    pub fn del_temporary_shared_storage_at(env: Env, key: Bytes) -> Result<(), Error>;
}

1.3 Facets

Facets are individual contracts that implement specific functionality. They are designed to operate using the shared storage provided via the DiamondProxy.

Facets MUST use the #[facet] macro. This macro automatically injects a standard initialization function with the signature init(env: Env, owner: Address, shared_storage: Address). During the diamond_cut process when a facet is added, the DiamondProxy calls this init function on the newly deployed facet instance, providing it with the necessary context (owner identity and the address of the SharedStorageLayer contract) to operate correctly.

#[contract]
pub struct ExampleFacet;

// The #[facet] macro ensures the contract has the standard init function  
#[facet]
#[contractimpl]
impl ExampleFacet {
    // The init function (init(env: Env, owner: Address, shared_storage: Address))
    // is automatically generated/injected by the #[facet] macro.
    // It typically stores the shared_storage address or sets up access helpers.

    // Standard facet function using shared storage via env helper methods
    pub fn update_user_balance(env: Env, user: Address, new_balance: i128) -> Result<(), Error> {
        // Use a helper provided by the Diamond framework/env extension
        let storage = env.shared_storage().instance();

        // Define a logical key (e.g., a Symbol or struct)  
        // The helper handles converting this logical key and the value (new_balance)  
        // into the raw Bytes needed by SharedStorageLayer.  
        let balance_key = symbol_short!("user_bal"); // Example key definition

        // Set the value using standard Soroban types  
        storage.set(&balance_key, &new_balance); // Handles serialization internally

        Ok(())  
    }

    pub fn get_user_balance(env: Env, user: Address) -> Result<i128, Error> {  
        let storage = env.shared_storage().instance();  
        let balance_key = symbol_short!("user_bal");

        // Get the value, helper handles deserialization from Bytes  
        let balance: i128 = storage.get(&balance_key).unwrap_or(0); // Example default

        Ok(balance)  
    }  
}

1.4 DiamondFactory

The DiamondFactory is responsible for deploying new diamond proxies, ensuring a standardized deployment process.

#[contract]
pub struct DiamondFactory;

#[contractimpl]
impl DiamondFactory {  
    pub fn init(env: Env, owner: Address);  
    // Deploys a new DiamondProxy and calls its init function  
    pub fn deploy_diamond(  
        env: Env,  
        owner: Address,  
        wasm_hash: BytesN<32>, // Wasm hash of the DiamondProxy implementation  
        salt: BytesN<32>,  
    ) -> Result<Address, Error>;  
}

2. Diamond Operations

2.1 Initialization

Diamond initialization follows these steps:

1. The DiamondFactory deploys a new DiamondProxy instance using deploy_from_contract.
2. The DiamondFactory calls the DiamondProxy.init method on the new instance, passing the owner address.
3. Inside DiamondProxy.init:
   • Sets the owner.
   • Deploys a dedicated SharedStorageLayer contract instance.
   • Calls init on the new SharedStorageLayer, passing the owner (or proxy address).
   • Stores the address of the SharedStorageLayer.
   • Initializes the internal selector-to-facet mapping (e.g., an empty Map<Symbol, Address>) and potentially inverse mappings needed for Loupe functions.

2.2 Diamond Cut (Adding/Replacing/Removing Facets)

The diamond_cut operation is the core mechanism for modifying the diamond's structure. It takes a vector of FacetCut actions.

// Action to perform on a set of selectors for a given facet WASM hash  
pub enum FacetAction {  
    Add,  
    Replace,  
    Remove,  
}

// Describes a single modification to the diamond's facet mapping  
pub struct FacetCut {  
    pub wasm_hash_of_facet: BytesN<32>, // Wasm hash of the facet code to use  
    pub action: FacetAction,  
    pub selectors: Vec<Symbol>,       // Function selectors to apply the action to  
}

Behavior of FacetAction:

• Add: Deploys a new facet contract instance using wasm_hash_of_facet. For each selector in selectors:
  • Checks if the selector already exists in the proxy's mapping. If it does, the operation MUST fail for this selector (and potentially the entire diamond_cut call) to prevent accidental overwrites. Selector collisions are disallowed on Add.
  • If the selector is new, adds it to the proxy's mapping, pointing to the newly deployed facet address. Updates Loupe data structures.
  • Calls the facet's injected init(owner, shared_storage_addr) function.
• Replace: Deploys a new facet contract instance using wasm_hash_of_facet. For each selector in selectors:
  • Updates the proxy's mapping to point the selector to the newly deployed facet address. If the selector did not previously exist, it is added. Updates Loupe data structures.
  • Calls the facet's injected init(owner, shared_storage_addr) function.
• Remove: For each selector in selectors:
  • Removes the selector from the proxy's mapping. If the selector does not exist, the operation should ideally succeed gracefully (idempotency). Updates Loupe data structures.
  • Note: Removing the last selector pointing to a facet does not automatically destroy the facet contract instance or its storage.

2.3 Facet Execution

When a function call is made to the DiamondProxy address (that isn't init, diamond_cut, or a Loupe function):

1. The fallback function is triggered.
2. The function selector (Symbol) is extracted.
3. The DiamondProxy looks up the selector in its internal mapping to find the target facet Address. If not found, it returns an error.
4. The DiamondProxy uses env.invoke_contract to delegate the call to the target facet's address, passing the original arguments (Vec).
5. Authentication context (caller identity) is preserved during the invoke_contract call.
6. The result (Val) or error from the facet is returned by the fallback function.

3. Shared Storage Access

Facets access the shared storage through helper methods provided via the env or a standard library/macro associated with the #[facet] macro. These helpers abstract away the direct interaction with the SharedStorageLayer contract and handle serialization/deserialization.

// Example within facet code:  
fn transfer_ownership(env: Env, new_owner: Address) {  
    // Get storage helper for persistent storage  
    let storage = env.shared_storage().persistent();

    // Define a logical key (e.g., Symbol or String literal)  
    let owner_key = symbol_short!("owner");

    // Use standard Soroban types directly. The `set` method handles  
    // serializing `owner_key` and `new_owner` into Bytes for the  
    // underlying call to SharedStorageLayer.set_persistent_shared_storage_at.  
    storage.set(&owner_key, &new_owner);

    // Similarly, `get` handles deserialization  
    let current_owner: Address = storage.get(&owner_key).expect("Owner not set");  
}

Key Naming Convention: Even though developers interact with helpers using logical keys (like Symbols or string literals), these keys are ultimately used to generate deterministic Bytes keys for the underlying storage. To prevent accidental collisions between different facets or different data items within a facet, developers MUST adopt clear and unique logical key names. A recommended practice is to use highly descriptive keys, potentially prefixed to indicate their purpose or owning facet (e.g., __token_balances,__config_adminFee). Disciplined logical key management remains essential for avoiding data corruption in the shared environment.

Design Rationale

Architecture

graph TD
    User["User"] --> DiamondProxy["DiamondProxy"]
    Factory["Factory"] --> DiamondProxy
    DiamondProxy --> LoupeStorage["Loupe Storage
    Selectors"]
    DiamondProxy --> FacetA["Facet A"]
    DiamondProxy --> FacetB["Facet B"]
    FacetA --> StorageHelper["Storage Helper"]
    FacetB --> StorageHelper
    StorageHelper --> SharedStorage["Shared Storage"]
    
    style User fill:#D5F5E3,stroke:#2ECC71,rx:5px
    style DiamondProxy fill:#D6EAF8,stroke:#3498DB,rx:5px
    style LoupeStorage fill:#F2F3F4,stroke:#95A5A6,rx:5px
    style Factory fill:#EAEDED,stroke:#5D6D7E,rx:5px
    style FacetA fill:#FCF3CF,stroke:#F1C40F,rx:5px
    style FacetB fill:#FCF3CF,stroke:#F1C40F,rx:5px
    style StorageHelper fill:#FADBD8,stroke:#E74C3C,rx:5px
    style SharedStorage fill:#F5EEF8,stroke:#8E44AD,rx:5px

Loading

Deployment Flow (Simplified)

sequenceDiagram
    participant User
    participant Factory
    participant Proxy
    participant Storage
    participant FacetA
    
    User->>Factory: deploy_diamond
    Factory->>Proxy: deploy
    Proxy->>Storage: deploy_storage
    
    User->>Proxy: diamond_cut
    Proxy->>FacetA: deploy_facet
    Proxy->>FacetA: init_facet
    Note over Proxy: Update selector mapping
    
    User->>Proxy: call function
    Proxy->>FacetA: invoke_contract
    FacetA->>Storage: set_storage
    FacetA-->>Proxy: return result
    Proxy-->>User: return result

Loading

Diamond Proxy vs ERC-2535

While inspired by Ethereum's ERC-2535 Diamond Standard, this implementation has several Soroban-specific differences:

1. Shared Storage Contract & Helpers: Uses a separate SharedStorageLayer contract combined with developer-friendly helper functions that handle serialization/deserialization, abstracting the underlying Bytes-based storage.
2. Authentication Forwarding: Leverages Soroban's invoke_contract to preserve the original caller's authentication context.
3. Symbol-Based Selectors: Uses Soroban's Symbol type for function selectors.
4. Facet Macro (#[facet]): Introduces a standardized macro for consistent facet initialization.
5. Standard Loupe Functions: Implements the core Loupe introspection functions directly on the DiamondProxy.

Feature of Ethereum Diamond Standard	Included in Proposed Stellar Implementation?	Strategic Reason for Inclusion/Exclusion
Full set of FacetCutAction (Add, Replace, Remove)	Yes	Complete upgrade capabilities are essential.
Standard Diamond Loupe facets for introspection	Yes (as functions on Proxy)	Provides essential on-chain discovery and introspection capabilities.
Specific Ethereum storage patterns (AppStorage)	No - Uses Soroban-native shared storage contract + helpers	Aligns with Soroban's data model, leverages platform features, provides type safety via helpers.
Events for DiamondCut	Implicit (via standard transaction events)	Soroban's event system can capture the diamond_cut call. Explicit events could be added later if needed.

Comparison with Standard Soroban Contract Upgrades

Feature	Diamond Proxy	Standard Upgrades (update_current_contract_wasm)
Upgrade Granularity	Individual facets (specific functionalities) can be upgraded independently via diamond_cut.	Entire contract must be replaced.
Storage Migration	Shared state persists automatically in SharedStorageLayer. Facets might need internal logic if their interpretation of shared data changes. Easier data format evolution.	Manual data migration often required between old and new contract instances.
Code Size Limit	Circumvents single contract size limits by splitting logic across multiple facet contracts.	Limited by Soroban's maximum contract code size.
Method Count	Virtually unlimited number of functions across all facets.	Limited by the number of public functions in a single contract.
Modularity	High - encourages separation of concerns into distinct facet contracts.	Low - typically leads to monolithic contract design.
Introspection	Built-in via standard Loupe functions on the proxy.	No standard on-chain introspection mechanism.
Deployment Complexity	Higher initially - requires deploying Proxy, SharedStorage, and multiple Facets. Upgrades require careful diamond_cut calls.	Lower - single contract deployment and update.
Gas Costs	Slightly higher per call due to delegation overhead (proxy lookup + invoke_contract cost). Loupe functions also add minor code size/deployment cost to proxy.	Slightly lower - direct function execution.
Dev Experience	Potentially better for teams (facet isolation). Shared storage helpers simplify state access. Requires understanding the Diamond pattern.	More straightforward monolithic development.
State Sharing	Built-in via SharedStorageLayer and ergonomic helpers.	Requires explicit cross-contract calls.

Security Concerns

Implementing the Diamond Standard requires careful attention to security:

1. Authorization of diamond_cut: MUST be strictly permissioned (owner/governance). Unauthorized access allows complete control over the contract logic.
2. Selector Management: Incorrect use of Replace can hijack functions. Add prevents collisions, but managing the overall selector space requires care. Tooling and rigorous reviews are essential.
3. Shared Storage Access Control: Facets have potential access to all shared data. Mitigation: Strict adherence to unique logical key naming conventions is crucial. Complex systems might implement additional checks within facets or use cryptographic techniques if fine-grained access control is needed beyond simple namespacing.
4. Facet Initialization: The #[facet] macro and init call pattern are critical for ensuring facets operate correctly. Failure here can break functionality.
5. Upgrade Coordination: New facet versions must be compatible with existing shared data structures or handle migration explicitly. Incompatible changes can corrupt state.
6. Reentrancy: Calls between facets (via the proxy) or from facets to external contracts require careful handling to prevent reentrancy attacks (use checks-effects-interactions, guards).
7. Loupe Function Gas Costs: While providing utility, the Loupe functions (especially facets()) might consume significant gas if the diamond has many facets/selectors. Consider potential DoS vectors if these are permissionless and heavily used.
8. Complexity: The multi-contract architecture increases overall system complexity, demanding thorough testing and auditing.

Security Concern	Potential Impact	Proposed Mitigation Strategy
Unauthorized diamond_cut	Malicious upgrades, logic replacement, DoS, theft of funds, contract state corruption.	Implement robust access control on diamond_cut (e.g., owner check, multi-sig, dedicated governance contract).
Storage collisions between facets	Data corruption, unexpected behavior, loss of state integrity.	Mandate and enforce strict logical key namespacing conventions (e.g., __facet_specific_key). Utilize type safety provided by storage helpers. Facets should validate data they read where critical.
Function selector misuse (Replace)	Unexpected routing of calls, loss of functionality, hijacking function implementations.	Careful review of selectors in diamond_cut. Use off-chain tooling. Clear documentation. Favor Add/Remove over Replace where possible. Audit Loupe function outputs after cuts.
Reentrancy vulnerabilities	Unexpected state changes during execution, potential financial loss.	Implement checks-effects-interactions pattern within facets. Use reentrancy guards where needed. Audit facet interactions. Minimize calls back to the diamond proxy from within a facet if possible.
Loupe function DoS/Gas limits	Transactions reverting due to gas limits, potential minor DoS vector.	Be mindful of gas usage for facets() on large diamonds. Potentially add pagination or limits if necessary, although standard Loupes typically don't. Off-chain indexers can also cache Loupe data.
Facet Initialization Failure	Facet unable to operate, potential reverts, inconsistent state.	Rely on the standardized #[facet] macro and initialization pattern. Ensure diamond_cut correctly calls init. Add runtime checks (is_initialized) within facets for critical operations if paranoid.
Complexity leading to errors	Unforeseen interactions, bugs in proxy/facet/storage logic.	Thorough unit testing (facets, proxy logic), integration testing (full system), and professional security audits. Clear documentation and modular design help manage complexity.

Future Considerations

Future enhancements could focus on:

1. Governance Integration: Standardizing patterns for integrating diamond_cut authorization with common governance contract frameworks.
2. Upgrade Coordination Tools: Developing off-chain tooling to help developers manage facet versions, generate diamond_cut parameters safely, visualize diamond structures using Loupe data, and simulate upgrades.
3. Cross-Diamond Communication: Exploring standardized patterns for secure and efficient communication between different diamond instances.
4. Event Standardization: Defining specific events emitted during diamond_cut (e.g., FacetAdded, FacetReplaced, FacetRemoved with details) to make tracking structural changes easier for off-chain services beyond just transaction data.
5. Advanced Storage Strategies: Exploring patterns for more structured data or access control within the SharedStorageLayer, potentially via specialized facets, though this adds complexity.

Examples and Use Cases

(Use cases remain the same as the previous version - DEX, Tokenization, Anchors, Governance, dApps, etc. - benefiting from modularity, upgradeability, and now easier introspection via Loupe).

Use Case Category	Specific Example Use Case	Benefits Enabled by Diamond Proxy Implementation
Decentralized Finance (DeFi)	Upgradeable lending/borrowing platform	Modular implementation of lending pools, interest models, collateral types as facets. Easier upgrades, feature additions (new collateral). Loupe allows users/integrators to verify platform components.
Tokenized Asset Management Platforms	Platform for diverse regulated/unregulated assets	Separate facets for issuance, transfer rules, compliance, distributions. Flexible management, adaptable to changing rules via facet upgrades. Loupe confirms active compliance rules.
Complex Decentralized Applications	Upgradeable decentralized marketplace	Modular design (users, listings, orders, payments, reviews). Easier maintenance, feature upgrades. Loupe helps integrations understand available marketplace functions.
Enhanced Anchor Functionality	Multi-asset/multi-currency anchor service	Separate facets for deposit/withdrawal logic per asset/currency. Simplifies adding new assets, managing specific integrations. Loupe verifies supported assets/functions.
On-Chain Governance	Evolving DAO framework	Facets for voting, proposals, treasury, dispute resolution. Allows DAO upgrades piece by piece. Loupe allows members to inspect the DAO's current ruleset/mechanisms on-chain.

Changelog

• v0.1.0 (2025-03-28): Initial draft. [#TBD]

Conclusion

The Diamond Proxy Standard for Soroban, emphasizing ergonomic shared storage access, offers a powerful and flexible architecture for smart contract development on Stellar. It enables enhanced modularity, safe upgradeability, and on-chain transparency, addressing key limitations of monolithic designs. By adopting this standard, developers can build more complex, maintainable, and adaptable decentralized applications.

The decision to propose a comprehensive Diamond Proxy implementation focuses on introducing core modularity, upgradeability, and introspection benefits while considering Soroban's architecture. Including diamond_cut, fallback, shared storage (with ergonomic helpers), facets, and Loupe functions addresses challenges associated with managing complex smart contract logic and facilitating controlled upgrades and discovery.

The trade-offs of increased architectural complexity and gas overhead for delegation are offset by the significant benefits, particularly for large or evolving systems. Successful adoption will depend on robust implementations, clear developer documentation, supporting tooling, and continued attention to security best practices, especially regarding diamond_cut authorization and shared storage discipline. This SEP provides a solid foundation for bringing these advanced capabilities to the Stellar ecosystem.

[fazzatti]

This proposal is really exciting! I love the modular approach with the Diamond Proxy architecture and the flexibility it brings through the use of facets. I was curious about best practices for managing shared storage or existing state during upgrades.

Are there strategies or recommendations for ensuring that changes in a facet or upgrades to the diamond itself don't inadvertently impact shared data or introduce unintended side effects?

Looking forward to learning more and seeing how this develops!

[tbraun96-nomyx]

Are there strategies or recommendations for ensuring that changes in a facet or upgrades to the diamond itself don't inadvertently impact shared data or introduce unintended side effects?

Thanks for the feedback and illuminating question, Fifo. I'll break this question down into two parts. What are:

• A: Strategies/recommendations to ensure shared storage data integrity on facet cuts, and
• B: Strategies/recommendations to ensure shared storage data integrity when upgrading a whole diamond

To start, I like thinking of a Diamond(Proxy) as an entire program. The different namespaces/modules/etc are facets, and the functions are selectors.

A: We can think of a facet cut as creating, updating, or deleting functions from a program. A facet cut does not upgrade the shared storage layer. Therefore, ensuring shared storage data integrity depends on the programmer making sure that the facets and selectors that are upgraded continue to use the shared storage in a consistent way.

B: Upgrading a whole diamond itself is not (currently) part of this proposal. However, it may be determined in the future that minor changes may be needed to logic of the Diamond contract itself that are beneficial for current and future users. Do we leave old deployments of Diamonds in a non-upgradable state, or, do we introduce some sort of migration logic? E.g., we can add a function called DiamondProxy::upgrade_from(env: Env, old_diamond_address: Address) and DiamondProxy::version(env: Env) -> u32. Such a function would have to have logic for transitioning between various diamond versions (e.g., from version 0 to 1, 1 to 2, etc) to ensure a smooth transition and lossless change in functionality as transformations are applied to each successive Diamond version. Thoughts?

[dmkozh]

Thanks for submitting this. Without diving too deep into motivation behind this, I would like to point out some issues that immediately strike me problematic or anti-patterns for Soroban. My main concern is authorization - with the specification provided I struggle to see how it would be possible to implement the pattern in the safe fashion while following the interface. But there is also a bunch of under-specification and usability concerns.

1. SEP scope

• I'm not certain what is the scope of this SEP. The pattern itself seems to be pretty self-contained and there is no need for the users to know about the diamond proxy being used (i.e. it's an implementation detail). Would you want to include these as SDK primitives? I'm afraid that might be too specific for the SDK. Or is this just to describe the deployment interfaces, so that the developer tools could work with them in a generic fashion? That seems more plausible to me, but it also requires more rigorous specification of the interactions during the deployments and upgrades.

2. Contract initialization

• Soroban supports constructors (__constructor function). I don't think init methods are necessary anywhere.
• Initialization logic may be quite complex and I think it requires more detailed specification, especially in the light of authorization concerns that I raise in the sections below

3. DiamondProxy contract

• I'm not sure owner should belong to the standard. There may be different models of ownership for different contracts. This seems like an implementation detail to me.
• I also think that 'owner' should rather be 'operator', right? Basically it should be the party that can modify the facets, but not necessarily manipulate the data directly. That's of course not perfect security-wise, but at least would prevent non-malicious mis-use.
• I'm not a fan the cryptic terminology being used. What are the 'Loupe functions'? Why do we have a 'diamond_cut' method and not just 'add_facet'? Could we just use descriptive names that use well-known terminology that would be obvious to any developer and not just someone who has worked with this pattern on EVM? We can always provide a simple 'migration guide' with the function name mapping. At the very least the specification should define the terms it's using, but I would still prefer more clear names.
• I think DiamondProxy should provide an upgrade function for the facets that verifies authorization of the proxy operator and upgrades the facet. Otherwise every facet would need a separate operator authority, which seems redundant and defeats the purpose of the pattern to some
  degree
• I don't fully understand the role of the read-only functions (named 'Loupe functions' here). Is there expectation that these would be necessary for the contract operation in some way? If so, in which way? On the surface this all seems like implementation details to me; ideally users shouldn't even know if they're using the 'diamond proxy' or a regular contract.
• On the usability topic, I think it would be useful to provide a way to generate a client for the DiamondProxy contract that exposes all the facet methods as methods on the DiamondProxy. That seems doable to me with the help of some macros.

3. Shared storage

• We don't need to serialize and deserialize the data to Bytes. That's an anti-pattern and it is not idiomatic for Soroban. You can use Val->Val map to store arbitrary types of data.
• I can't see any information on storage authorization. This is critical for this pattern to work properly. I don't think the proposed interface even allows for authorization. Keep in mind that Soroban doesn't provide an invoker or call stack getters, which means that storage doesn't know who calls it. I'm pretty sure that the only way to make it work is to pass the additional parameter authorizer: Address that will have then require_auth called for it. The 'facets' will just pass their address there. Storage will need to of course ensure that authorizer is one of the registered facets.
• Shared instance storage is a weird concept to grasp. I don't think it is necessary and it kind of contradicts the purpose of the instance storage. Keep in mind, that instance storage has a limited size and providing a shared access to it is a footgun (you just risk running out of space). Instead, instance storage should be private to the storage contract, and it may contain storage metadata (such as the list of the facets that have access to it).
• Why does storage have an owner? What is the role of the owner? I think it would probably make sense for the owner to only be able to register and unregister the facets that have access to the storage, and the owner probably should be the DiamondProxy contract instance. That all requires more detailed specification.

3.1 Key naming convention

• I don't think the suggestion to use 'highly descriptive names' like __config_adminFee makes much sense in Soroban, given that it's possible to use enums and structs as keys
• I think a sensible thing to do would be to define the DataKey enum (or multiple similar enums) in the shared storage library. Then it will be just a shared enum that any facet can use. That would also be idiomatic Soroban usage.
• Ultimately this may be a bit too low level implementation detail and probably it doesn't need to be specified here at all. But at least we shouldn't mis-lead developers into anti-patterns.

4. Facets

• The facets must use [facet] macro is insufficient specification. If we're going for a SEP, we should define the actual interfaces that a facet implements and just mention that they can be auto-generated. Currently there is no way of telling what the facet macro does.
• I think facet contracts should provide initialization and upgrade functions with well defined semantics. Probably this is implied here, but we need to state that explicitly.
• I don't think shared storage can be accessible via env, unless we modify SDK (which we probably won't do). In any case, it would be useful to go a bit lower level and specify the storage interaction semantics. Helpers can be created on top of that.
• Upgrade semantics should be specified explicitly. I think the operator should start the upgrade process with the DiamondProxy entry point (that doesn't exist yet). Then DiamondProxy would call the upgrade method on the facet contract. Facet contract must authorize the upgrade requester here and it must be DiamondProxy. Then DiamondProxy upgrade method may also call data migration method on the facet. This is my rough understanding, but there may be more to this - it all requires more detailed specification.

5. DiamondFactory

• I'm not sure if that's necessary in the standard (but that really depends on its scope). But if it is necessary, then we should specify what exactly does it do, because currently it's just an arbitrary interface.
• It could also probably be just a constructor, but that really depends on what needs to happen during the deployment.

6. Security Concerns

• I apologize in advance if I'm wrong, but this whole section looks AI-generated to me. Even if I'm wrong, it's at misleading.
• Some of the concerns listed are not actually security concerns (gas costs, complexity). FWIW there is no 'gas' on Soroban at all, and while the cost may be of concern, this probably requires much more rigorous analysis to make a conclusion about the costs. In any case, specifically read-only functions like facets() are not a concern at all because they don't even need to be executed on-chain.
• There is no re-entrancy in Soroban
• The storage access authorization is a significant concern and it's not addressed here at all
• Probably the whole section needs to be revisited after the other items are specified more precisely.

[tbraun96-nomyx]

@dmkozh Thanks for the thorough and highly useful feedback.

Concerning authorization, this is the elephant in the room. We did not address this in the first version of the SEP (filed over 3 months ago), but, have a mechanism ensuring authorized access to facets and shared storage that was developed several months after this initial filing. Describing the security mechanisms we've since developed in written will be a section unto itself.

Would you want to include these as SDK primitives? I'm afraid that might be too specific for the SDK.

Yes, ideally. Though, the current proposal requires deploying bytecode in actu and thus would require changes to conventions; this has prompted us to consider the possibility, as you implied, that the scope of this filing is too broad for the SDK, and would potentially require a approach similar to OpenZeppelin via a custom library if conventions on what is/isn't allowed in the SDK are adhered to. There are downsides to this, which is discussed hereafter.

I'm not a fan the cryptic terminology being used.

The naming conventions are mostly from Ethereum. We can certainly rename the functions to reduce the initial cognitive complexity of understanding an inherently new "language" for Stellar-native developers. However, there is a commercial/marketing benefit in keeping naming conventions consistent with Ethereum's. By providing a more seemless migration/onboarding process for the large Ethereum developer community, the fewer barriers to entry Ethereum developers experience. The less they have to learn, the better experience and the higher the retention rate. Ethereum has lots of developers, and having them come to Stellar — and stay in it — is in the best interest of Stellar's ecosystem.

I don't think shared storage can be accessible via env, unless we modify SDK (which we probably won't do).

Currently, the code does not actually modify the SDK and instead implements traits for the concrete foreign type Env. These traits contain the functions. Since there has been pushback against changes in the SDK itself, this suggests a library (as mentioned before) would be a more coherent approach. The obvious downside to adhering to past conventions is for the same reason provided concerning the growth of Stellar by making everything easy/familiar for migrating developers. While I see the developer's argument for why to hold-on to convention, this negatively impacts the (financial) best interest of the Stellar ecosystem.

Upgrade semantics should be specified explicitly.

It's listed in the documentation for FacetAction::Replace with an associated dialogue on it (i.e., "Updates the proxy's mapping to point the selector to the newly deployed facet address."). We could make it clearer in the next version since it was perceived not to exist.

Overall, your feedback will be used to improve the next iteration. Thereafter, we will need to discuss what is in the best interest of the Stellar ecosystem to inform how the final implementation is detailed.

[dmkozh]

that the scope of this filing is too broad for the SDK,

To be clear, the scope is too narrow, not too broad. SDK is generally not meant to include the contract implementations, it provides the primitives instead.

a approach similar to OpenZeppelin via a custom library if conventions on what is/isn't allowed in the SDK are adhered to.

If you go for a library approach (which I think is indeed the most sensible thing to do), then my question remains: what do we need this SEP for? To be more specific, what are the parts of it that all the ecosystem developers should follow for the sake of compatibility? What are the interfaces that one needs to use to interact with a diamond proxy contract?
Discussing the implementation details and security with the ecosystem is great, but I'm not sure what is the outcome that we're trying to reach here. If the outcome is just the library, then I'm not sure it needs to be a SEP - anyone can just go ahead and use the library. Basically, we need to understand what part should actually be the standard, and what part is just an implementation detail.

However, there is a commercial/marketing benefit in keeping naming conventions consistent with Ethereum's.

It might be hard to measure this, but I'm not sure if the value of just keeping a couple of terms the same as in Ethereum is too high. Stellar is quite different from EVM in multiple aspects, there are primitives unique to either platform and ultimately there going to be a learning curve. So it's not clear that adapting some of the slang would have a tangible benefit, given that most of the surrounding interfaces will have different types, signatures and maybe even different semantics (not to mention that stuff like 'loupe functions' isn't even appearing much in the intended meaning in Google search). Anyways, that's not the most important issue here, I think we can revisit the naming after finalizing the interfaces. The role for a lot of functions is not immediately clear (especially the read-only functions), so we'd need to figure that out first.