DiamondLib Library¶

Overview¶

DiamondLib is a specialized diamond storage library that provides access to the Gemforce-specific diamond storage structure. This library extends the standard Diamond pattern with application-specific storage management for the Gemforce platform.

Key Features¶

• Gemforce Diamond Storage: Provides access to platform-specific diamond storage
• Storage Isolation: Uses unique storage position for Gemforce diamond data
• ERC Standards Integration: Imports and integrates with ERC721, ERC165, and other standards
• Diamond Pattern Extension: Extends the standard diamond pattern for Gemforce use cases

Storage Structure¶

Diamond Storage Position¶

The library uses a unique storage position to avoid conflicts with other diamond implementations:

bytes32 internal constant DIAMOND_STORAGE_POSITION = 
    keccak256("diamond.nextblock.bitgem.app.DiamondStorage.storage");

This ensures that Gemforce diamond storage is isolated from other diamond implementations that might be used in the same contract ecosystem.

Core Functions¶

Storage Access¶

diamondStorage()¶

function diamondStorage() internal pure returns (DiamondStorage storage ds)

Returns the Gemforce-specific diamond storage struct using assembly for gas-efficient access.

Returns: - ds: The diamond storage struct containing all platform-specific data

Implementation Details: - Uses assembly for direct storage slot access - Provides gas-efficient storage access pattern - Ensures consistent storage location across all facets

Dependencies¶

The library imports several key interfaces and libraries:

Standard Interfaces¶

• IERC165: Interface detection standard
• IERC721: Non-fungible token standard
• IERC721Metadata: NFT metadata extension

Diamond Interfaces¶

• IDiamondCut: Diamond upgrade operations
• IDiamondLoupe: Diamond introspection
• IERC173: Contract ownership standard
• DiamondStorage: Platform-specific storage structure
• IToken: Token definition interface

Related Libraries¶

• LibDiamond: Core diamond functionality
• ERC721ALib: ERC721A implementation library

Initialization¶

• DiamondInit: Diamond initialization contract

Usage Patterns¶

Accessing Diamond Storage¶

import { DiamondLib } from "./libraries/DiamondLib.sol";

contract MyFacet {
    function someFunction() external {
        DiamondStorage storage ds = DiamondLib.diamondStorage();
        // Access platform-specific storage
    }
}

Integration with Facets¶

// In a facet contract
function getPlatformData() external view returns (SomeData memory) {
    DiamondStorage storage ds = DiamondLib.diamondStorage();
    return ds.platformSpecificData;
}

Storage Architecture¶

Separation of Concerns¶

• LibDiamond: Handles core diamond functionality (facet management, upgrades)
• DiamondLib: Manages Gemforce-specific storage and data structures
• Facet Libraries: Handle domain-specific logic and storage

Storage Isolation Benefits¶

1. Conflict Prevention: Unique storage position prevents conflicts
2. Upgrade Safety: Isolated storage reduces upgrade risks
3. Platform Specificity: Allows platform-specific optimizations
4. Modularity: Clean separation between core and platform features

Integration Points¶

Core Diamond System¶

• Works alongside LibDiamond for complete diamond functionality
• Provides platform-specific storage while LibDiamond handles upgrades
• Integrates with diamond initialization processes

Token Systems¶

• Integrates with ERC721A library for NFT functionality
• Supports token definition structures
• Enables platform-specific token features

Facet Architecture¶

• Used by all Gemforce facets for consistent storage access
• Provides unified storage interface across the platform
• Enables cross-facet data sharing

Best Practices¶

Storage Access¶

1. Consistent Usage: Always use DiamondLib.diamondStorage() for platform storage
2. Gas Efficiency: Leverage assembly-based storage access for performance
3. Storage Isolation: Keep platform storage separate from facet-specific storage

Development Patterns¶

1. Import Consistency: Always import DiamondLib in facets needing platform storage
2. Storage Structure: Follow established patterns for storage organization
3. Upgrade Compatibility: Ensure storage changes are upgrade-compatible

Security Considerations¶

1. Storage Position: Never modify the DIAMOND_STORAGE_POSITION constant
2. Access Control: Implement proper access controls for storage modifications
3. Data Integrity: Validate data before storing in diamond storage

Relationship to LibDiamond¶

Migration and Upgrades¶

Storage Compatibility¶

• Maintains backward compatibility with existing storage layouts
• Supports incremental storage structure updates
• Provides migration paths for storage changes

Upgrade Considerations¶

• Storage position remains constant across upgrades
• New storage fields can be added safely
• Existing storage fields should not be modified

Related Documentation¶

• LibDiamond Library - Core diamond functionality
• Diamond Standard Overview - Diamond pattern implementation
• IDiamond Interface - Diamond interface specification
• ERC721A Library - NFT implementation library
• Diamond Factory Library - Diamond deployment utilities

Technical Notes¶

Assembly Usage¶

The library uses assembly for storage access to achieve gas efficiency:

assembly {
    ds.slot := position
}

This pattern is safe and widely used in diamond implementations for optimal performance.

Storage Position Calculation¶

The storage position is calculated using:

keccak256("diamond.nextblock.bitgem.app.DiamondStorage.storage")

This ensures a unique, deterministic storage location that won't conflict with other systems.