[Temp Check]ENSIP Draft: Granular Name Assignment (GNA) and Policy-Based Delegation

💬 General Discussion
1

ENSIP Draft: Granular Name Assignment (GNA) and Policy-Based Delegation

Abstract

This document proposes the Granular Name Assignment (GNA) system, which enables fine-grained, revocable, and time-limited delegation of specific operational rights over ENS names and subdomains to non-owners, including smart contracts.

GNA uses a dedicated GranularResolver and a complementary ENSNamingDelegateGranular controller to provide a robust Policy Enforcement Layer for ENS. This design supports advanced use cases such as emergency controls, access allow/block lists, and detailed permission monitoring.

The system operates through a two-contract architecture: the delegation controller manages permission policies, while the resolver enforces these policies at the point of record modification, ensuring all operations comply with the established delegation rules.

Motivation

In the current ENS architecture, control is binary: only the registered owner can perform name operations, and access cannot be shared or differentiated by function. Name Wrapper and Fuses are valuable for restricting structural changes, but there is no way to positively assign defined sets of operational privileges to external parties or smart contracts.

GNA is Complementary: GNA solves a key limitation. Fuses restrict and lock-down structure (transfer and configuration rights) while GNA enables selective operational delegation—deciding who can update what records. With GNA, organizations can:

  1. Segregate Duties (SoD): Restrict ETH address changes to a secure “treasury” while allowing other teams to update less sensitive records, reducing security exposure in the event of a compromise.
  2. Automate Policy Enforcement: Assign authority for certain records directly to on-chain automation (like governance contracts or automated resolvers) without giving up all control.
  3. Time-Limit Delegations: Ensure all delegated rights automatically expire at a set time, eliminating risks from forgotten or stale access.
  4. Rapid Emergency Intervention: Instantly revoke or pause delegated permissions, enabling swift reaction to incidents.

Specification

GNA is composed of two main contracts: ENSNamingDelegateGranular (the policy engine) and GranularResolver (the enforcer).

1. ENSNamingDelegateGranular (GranularAssignmentController)

The ENSNamingDelegateGranular contract serves as the policy engine for the GNA system. It maintains the complete delegation matrix, tracking which addresses hold which permissions for which nodes, along with expiration times and security metadata.

Core Delegation Operations:

  • addDelegate(bytes32 node, address delegate, uint256 operations, uint256 expiresAt): Creates a new delegation entry granting the specified bitmask of operations to the delegate address until the expiration timestamp. Only the ENS Registry owner of the node may call this function. The expiration timestamp must be in the future and within the maximum delegation duration limit if one is set.

  • removeDelegate(bytes32 node, address delegate): Permanently removes all permissions for a delegate on the specified node. This operation fails if the delegate is locked. Only the ENS Registry owner may call this function.

  • updateDelegate(bytes32 node, address delegate, uint256 operations, uint256 expiresAt): Modifies an existing delegation, allowing changes to the permission bitmask and/or expiration time. The delegate must not be locked for this operation to succeed. Only the ENS Registry owner may call this function.

  • getDelegateInfo(bytes32 node, address delegate): Returns a DelegatePermission struct containing the complete delegation state: allowed operations bitmask, expiration timestamp, enabled status, locked status, creation timestamp, and creator address.

Advanced Security Features:

  • lockDelegate(bytes32 node, address delegate): Sets the locked flag for a delegate, preventing its removal until unlocked. This mechanism protects critical delegations from accidental deletion. Only the ENS Registry owner may call this function.

  • unlockDelegate(bytes32 node, address delegate): Removes the locked status, allowing the delegate to be removed if needed. Only the ENS Registry owner may call this function.

  • enableDelegate(bytes32 node, address delegate): Activates a disabled delegate, restoring its permissions without modifying the underlying delegation configuration.

  • disableDelegate(bytes32 node, address delegate): Temporarily deactivates a delegate, suspending its permissions while preserving the delegation configuration for future reactivation.

  • emergencyPause(bytes32 node, bool paused): Globally pauses or unpauses all GNA-based operations for a node. When paused, no delegate may perform operations, regardless of their permissions. Only the ENS Registry owner may call this function.

  • emergencyRevokeAll(bytes32 node): Immediately removes all delegations for a node, resetting it to owner-only control. This operation bypasses lock protections and should be used only in security emergencies. Only the ENS Registry owner may call this function.

  • setMaxDelegationDuration(bytes32 node, uint256 maxDuration): Sets the maximum allowed duration for new delegations on a node, measured in seconds from the current block timestamp. This prevents excessively long delegations and helps enforce organizational policies. Only the ENS Registry owner may call this function.

Access Control Lists:

  • toggleWhitelist(bytes32 node, bool enabled): Enables or disables whitelist mode for a node. When enabled, only addresses on the whitelist may be added as delegates.

  • updateWhitelist(bytes32 node, address delegate, bool added): Adds or removes an address from the whitelist for a node. Only the ENS Registry owner may call this function.

  • toggleBlacklist(bytes32 node, bool enabled): Enables or disables blacklist mode for a node. When enabled, addresses on the blacklist cannot be added as delegates.

  • updateBlacklist(bytes32 node, address delegate, bool added): Adds or removes an address from the blacklist for a node. Only the ENS Registry owner may call this function.

2. GranularResolver

The GranularResolver contract implements the standard ENS Resolver interface (EIP-137, EIP-205) and enforces GNA permission checks on every mutating operation. It serves as the enforcement layer, querying the ENSNamingDelegateGranular contract to verify permissions before allowing any record modifications.

Access Control Logic:

Before executing any record-setting function, the resolver performs the following validation sequence:

  1. Owner Check: If the caller is the ENS Registry owner for the node, the operation is permitted (standard ENS behavior). This check may be bypassed if owner override is disabled for the node.

  2. Delegate Check: If the owner check fails or is disabled, the resolver queries ENSNamingDelegateGranular to verify:

    • The caller is a registered delegate for the node
    • The delegate is enabled (not disabled)
    • The delegation has not expired (current timestamp < expiresAt)
    • The node is not in emergency pause state
    • The delegate’s permission bitmask includes the specific operation being attempted
    • If whitelist mode is enabled, the delegate must be on the whitelist
    • If blacklist mode is enabled, the delegate must not be on the blacklist

  3. Permission Bitmask Validation: The resolver extracts the required permission constant from the function being called and verifies that the delegate’s allowedOperations bitmask has the corresponding bit set.

Security & Flexibility Features:

  • toggleOwnerOverride(bytes32 node, bool disabled): Allows the ENS Registry owner to voluntarily disable their direct operational rights for a node. When disabled, all record changes must flow through GNA delegations, even for the owner. This provides an additional security layer by forcing all operations through the delegation audit trail.

  • Time-Based Validation: All delegate permissions are automatically invalidated after their expiration timestamp, requiring explicit renewal for continued access.

  • Emergency Integration: The resolver respects emergency pause states and revocation commands from the delegation controller, ensuring rapid response to security incidents.

  • Access List Enforcement: Whitelist and blacklist controls are enforced at the resolver level, providing defense-in-depth security.

Supported Resolver Functions:

The resolver implements all standard ENS resolver functions with permission enforcement:

  • setAddr(bytes32 node, address addr)
  • setAddr(bytes32 node, uint256 coinType, bytes memory addr)
  • setText(bytes32 node, string calldata key, string calldata value)
  • setContenthash(bytes32 node, bytes calldata hash)
  • setPubkey(bytes32 node, bytes32 x, bytes32 y)
  • setABI(bytes32 node, uint256 contentType, bytes calldata data)
  • setZonehash(bytes32 node, bytes32 hash)
  • setTTL(bytes32 node, uint64 ttl)
  • setResolver(bytes32 node, address resolver)
  • setSubnodeOwner(bytes32 node, bytes32 label, address owner)
  • setSubnodeRecord(bytes32 node, bytes32 label, address owner, address resolver, uint64 ttl)

3. Permission Mask Constants

The permission system uses a bitmask approach where each operation type is assigned a unique bit position. Delegates can be granted multiple permissions by combining these constants using bitwise OR operations. This design allows for efficient storage and permission checking while maintaining flexibility.

Constant Bit Position Value Functions Controlled Description
MANAGE_SUBDOMAINS 1 << 0 1 setSubnodeOwner, setSubnodeRecord Create and transfer subdomains, including nested subdomains
SET_ADDR_RECORD 1 << 1 2 setAddr (all coin types) Set Ethereum and multi-chain address records
SET_TEXT_RECORD 1 << 2 4 setText (all keys) Set arbitrary text records (e.g., email, URL, description)
SET_CONTENT_HASH 1 << 3 8 setContenthash Set IPFS, Swarm, or other content hash records
SET_PUBKEY 1 << 4 16 setPubkey Set public key records for cryptographic operations
SET_ABI 1 << 5 32 setABI Set contract ABI records for interface definitions
SET_ZONEHASH 1 << 6 64 setZonehash Set DNS zone hash records for DNSSEC integration
SET_TTL 1 << 7 128 setTTL Set time-to-live values for caching
SET_RESOLVER 1 << 8 256 setResolver Change the resolver contract for a node
SET_OWNER 1 << 9 512 setOwner Transfer ownership in the ENS Registry
SET_FUSES 1 << 10 1024 setFuses Modify NameWrapper fuse settings

Permission Combination Examples:

  • Grant text and address update rights: SET_TEXT_RECORD | SET_ADDR_RECORD (value: 6)
  • Grant all record-setting permissions except ownership: SET_ADDR_RECORD | SET_TEXT_RECORD | SET_CONTENT_HASH | SET_PUBKEY | SET_ABI | SET_ZONEHASH | SET_TTL (value: 254)
  • Grant full control including subdomain management: All permissions combined (value: 2047)

4. Delegation Structure

struct DelegatePermission {
    uint256 allowedOperations;  // Bitmask indicating which functions the delegate controls
    uint256 expiresAt;          // Hard expiration (timestamp); delegation is void after this
    bool enabled;               // If false, rights are suspended until re-enabled
    bool locked;                // If true, this delegate cannot be removed until unlocked
    uint256 createdAt;          // When this delegation was established (for auditing)
    address createdBy;          // Which address created (or last updated) the entry
}

5. System Workflow

The GNA system operates through the following workflow:

  1. Initial Setup: The ENS Registry owner deploys or connects to an ENSNamingDelegateGranular contract and sets a GranularResolver as the resolver for their node.

  2. Delegation Creation: The owner calls addDelegate() on the delegation controller, specifying:

    • The node (namehash) to delegate permissions for
    • The delegate address (can be an EOA or smart contract)
    • The permission bitmask (operations to allow)
    • The expiration timestamp

  3. Permission Enforcement: When a delegate attempts to modify a record:

    • The delegate calls a resolver function (e.g., setText()) on the GranularResolver
    • The resolver queries the ENSNamingDelegateGranular contract to verify permissions
    • If all checks pass (valid delegate, not expired, has required permission, not paused), the operation proceeds
    • If any check fails, the operation reverts with an appropriate error message

  4. Permission Management: The owner can:

    • Update permissions using updateDelegate()
    • Temporarily disable using disableDelegate() without removing the delegation
    • Lock critical delegations using lockDelegate() to prevent accidental removal
    • Remove delegations using removeDelegate() (unless locked)

  5. Emergency Response: In case of security incidents, the owner can:

    • Pause all operations using emergencyPause()
    • Revoke all delegations using emergencyRevokeAll()
    • Disable specific delegates using disableDelegate()

  6. Expiration Handling: When a delegation expires, the delegate automatically loses all permissions. The owner must create a new delegation or update the existing one with a new expiration time to restore access.

Rationale

The GNA system addresses a fundamental limitation in the current ENS architecture: the inability to share operational control without transferring ownership. This limitation creates significant challenges for organizations managing ENS names, as it forces a choice between centralized control and complete ownership transfer.

Hierarchical Management Architecture:

GNA enables a hierarchical management model where a parent domain can delegate specific functional rights to different teams or smart contracts, with granular control extending through multiple subdomain levels. For example:

  • A treasury team can be granted SET_ADDR_RECORD permission to manage payment addresses
  • A development team can be granted SET_TEXT_RECORD and SET_CONTENT_HASH permissions for website management
  • A marketing team can be granted SET_TEXT_RECORD permission for social media links
  • An automation contract can be granted time-limited permissions for automated updates

This capability is currently impossible to achieve using only standard ENS features, which provide only binary ownership control.

Security-First Design Principles:

The implementation incorporates multiple security layers that address enterprise and institutional requirements:

  • Time-limited rights: All delegations require mandatory expiration timestamps, preventing perpetual access from forgotten or compromised keys. This automatic expiration mechanism eliminates the risk of stale permissions persisting indefinitely.

  • Emergency controls: The system provides multiple emergency response mechanisms including global pause, instant revocation, and delegate disabling. These controls enable rapid response to security incidents without requiring complex multi-step recovery procedures.

  • Access lists: Whitelist and blacklist mechanisms provide defense-in-depth security, allowing organizations to enforce additional access policies beyond basic permission grants.

  • Auditability: Every delegation operation records creation timestamps and creator addresses, providing complete visibility into permission changes for compliance and security monitoring.

  • Lock mechanism: Critical delegations can be locked to prevent accidental removal, protecting essential operational capabilities from configuration errors.

Complementary to Existing ENS Features:

GNA is designed to complement, not replace, existing ENS security features. Name Wrapper and Fuses provide structural protection (preventing transfers and configuration changes), while GNA provides operational delegation (controlling who can update records). Together, these systems enable sophisticated security architectures that were previously impossible.

Security Considerations

The GNA system introduces powerful delegation capabilities that require careful risk assessment and operational discipline. The following considerations are critical for secure deployment:

  1. Resolver Enforcement Dependency (Critical): All GNA security protections depend on the GranularResolver being set as the resolver for the node. The ENS Registry owner retains the fundamental ability to call setResolver() on the Registry, which would instantly revert control to the owner and bypass all GNA delegation rules. This is an unavoidable architectural constraint inherent to the ENS ownership model. Organizations must implement additional controls (such as multi-signature wallets or timelock contracts) to protect the Registry owner key if they wish to prevent this bypass mechanism.

  2. Subdomain Delegation Scope (High Risk): Delegating MANAGE_SUBDOMAINS grants the delegate the ability to arbitrarily create and assign ownership of subdomains at any nesting level. A delegate with this permission can create sub-subdomains and transfer their ownership, potentially creating permanent splits in the namespace. Owners must only delegate this permission to highly trusted parties with clear operational boundaries. Consider using time-limited delegations and monitoring systems to track subdomain creation activities.

  3. Permission Bit Collision Risks (Medium Risk): As the ENS ecosystem evolves and new resolver functions are introduced, care must be taken to ensure future features map to unique, non-conflicting bits in the permission mask. The current implementation uses 11 bits (positions 0-10), leaving 245 bits available for future expansion. However, any new permission constants must be carefully assigned to avoid conflicts with existing permissions or create unexpected privilege combinations.

  4. Time-Bound Access Operational Complexity (Medium Risk): While time-bound delegation enhances security by preventing perpetual access, it also introduces operational complexity. Organizations must implement robust monitoring and renewal processes to prevent service disruptions when permissions expire. Consider implementing automated renewal systems or alerting mechanisms that notify administrators before delegations expire. The setMaxDelegationDuration function can help enforce organizational policies on delegation lifetimes.

  5. Emergency Control Attack Surface (High Risk): The emergency controls (emergencyPause, emergencyRevokeAll) provide powerful security tools but also introduce additional attack vectors if the emergency control keys are compromised. An attacker with access to the Registry owner key could use these functions to disrupt operations or lock out legitimate delegates. Organizations should implement key management best practices, including hardware wallet storage, multi-signature requirements, and key rotation policies.

  6. Lock Mechanism Bypass (Low-Medium Risk): The emergencyRevokeAll function bypasses lock protections, which is intentional for emergency response but could be misused. Organizations should carefully consider when to use this function versus individual delegate removal, as it provides no granularity and affects all delegates simultaneously.

  7. Access List Configuration Errors (Low Risk): Incorrect whitelist or blacklist configuration could inadvertently block legitimate delegates or allow unauthorized access. Organizations should implement testing procedures and gradual rollout strategies when enabling access list features.

  8. Gas Cost Considerations (Operational): The permission checking mechanism adds gas overhead to every resolver operation. While the implementation is optimized for efficiency, organizations should be aware that delegate operations will cost more gas than direct owner operations. This is a necessary trade-off for the added security and flexibility.

Implementation Status

The GNA system has been fully implemented and is production-ready with the following features:

Core Implementation

  • ENSNamingDelegateGranular.sol: Complete policy engine with all security features
  • GranularResolver.sol: Full ENS resolver implementation with permission enforcement
  • Interface Contracts: Complete interface definitions for all components

Security Features (Implemented)

  • Time-bound delegation with mandatory expiration
  • Emergency pause and revocation capabilities
  • Whitelist/blacklist access control
  • Delegate locking mechanism
  • Comprehensive audit logging
  • Security alert system

Testing & Quality Assurance

  • 47 comprehensive tests covering all core functionality, edge cases, and security scenarios
  • 100% test coverage across all contracts and functions
  • Gas optimization with efficient storage patterns and minimal external calls
  • EIP standards compliance with all relevant ENS specifications
  • Fork testing against mainnet ENS contracts for integration validation

Production Readiness

  • Mainnet integration with hardcoded ENS contract addresses for production deployment
  • NameWrapper compatibility for full ENS ecosystem support including wrapped names
  • EIP standards compliance: EIP-137 (Resolver Interface), EIP-165 (Interface Detection), EIP-205 (ABI Support), EIP-619 (Content Hash), EIP-634 (Text Records), EIP-1577 (IPFS), EIP-1844 (DNS)
  • Factory pattern implementation for efficient contract deployment
  • Comprehensive error handling with descriptive revert messages
  • Event emission for all state changes to enable off-chain monitoring and indexing

Future Work and Improvements

Based on technical analysis and implementation experience, the following enhancements are planned for future versions:

  1. Multi-signature Delegation Management: Integration with multi-signature wallet standards (e.g., Gnosis Safe) to require multiple signatures for delegation operations, providing enhanced security for critical permission changes.

  2. Conditional Permissions: Implementation of conditional permission grants based on external factors such as time-of-day restrictions, governance vote outcomes, oracle data feeds, or other on-chain conditions. This would enable more sophisticated access control policies.

  3. Automated Permission Management: Smart contract-based automation systems for permission renewal, rotation, and lifecycle management. This would reduce operational overhead and prevent service disruptions from expired permissions.

  4. Advanced Analytics and Monitoring: Comprehensive off-chain reporting and analytics systems for delegation usage patterns, security monitoring, and compliance auditing. Integration with indexing services to provide real-time visibility into permission states.

  5. Layer 2 Deployment: Optimization and deployment on Layer 2 networks (e.g., Arbitrum, Optimism, Polygon) to reduce gas costs for delegation operations while maintaining mainnet security guarantees through bridge mechanisms.

  6. Permission Templates: Pre-configured permission sets for common use cases (e.g., “Marketing Team”, “Development Team”, “Treasury”) to simplify delegation setup and reduce configuration errors.

  7. Delegation Inheritance: Support for hierarchical permission inheritance where subdomain delegations can inherit or extend parent domain permissions, reducing configuration complexity for large namespace hierarchies.

Implementation Details

The reference implementation is available for review and deployment:

Repository: https://github.com/accessor-io/ens-granular-name-assignment

ENS Mainnet Contract Addresses:

  • ENS Registry: 0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e
  • NameWrapper: 0xD4416b13d2b3a9aBae7AcD5D6C2BbDBE25686401

Contract Architecture:

  • ENSNamingDelegateGranular: Policy engine contract managing all delegation state
  • GranularResolver: Resolver implementation enforcing permission checks
  • ENSNamingDelegateFactory: Factory contract for deploying new delegation controllers
  • GranularResolverFactory: Factory contract for deploying new resolver instances

Development and Testing:

  • Test suite: 47 tests covering all functionality with 100% passing rate
  • Test coverage: 100% coverage across all contracts and functions
  • Gas optimization: Efficient storage patterns and minimal external calls
  • Fork testing: Validated against mainnet ENS contracts

Deployment:

  • Contracts are ready for mainnet deployment
  • Factory pattern enables efficient deployment of multiple instances
  • All contracts include upgrade considerations for future enhancements

Security Status:

  • Code review completed
  • Ready for professional security audit
  • All known vulnerabilities addressed in current implementation

Copyright

Copyright and related rights waived via CC0.