Scoped Approval Interface

A standardized smart contract interface for restricted (scoped) approval of token IDs, enabling fine-grained operator permissions for CBC-1155, CBC-721, and similar token contracts.

Abstract

This standard defines a common interface for restricted (scoped) approval in token contracts with an "ID" domain, such as CBC-1155 or CBC-721. CBC-1761 enables fine-grained operator permissions by defining "scopes" of one or more token IDs, allowing users to grant or revoke operator rights for specific groups of tokens. This improves security and flexibility for asset management, gaming, and enterprise use cases.

Motivation

Traditional approval mechanisms in CBC-1155 and CBC-721 allow operators to manage all of a user's tokens, which can lead to excessive risk if the operator is compromised. CBC-1761 introduces the concept of scopes, enabling users to restrict operator permissions to specific token groups or domains. This reduces risk and enables new use cases, such as regional asset management, game developer collaboration, and differentiated access for high- and low-value tokens.

Specification

Interface

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

/**
 * Note: The CBC-165 identifier for this interface is 0x30168307.
 */
interface ICBC1761 {
    // --- Events ---
    event ApprovalForScope(address indexed owner, address indexed operator, bytes32 indexed scope, bool approved);
    event IdsAddedToScope(uint256 indexed idStart, uint256 indexed idEnd, bytes32 indexed scope);
    event IdsRemovedFromScope(uint256 indexed idStart, uint256 indexed idEnd, bytes32 indexed scope);
    event ScopeURI(string value, bytes32 indexed scope);

    // --- Core Functions ---
    function scopeCountForId(uint256 id) external view returns (uint32);
    function scopeForId(uint256 id, uint32 scopeIndex) external view returns (bytes32);
    function scopeUri(bytes32 scope) external view returns (string memory);
    function setApprovalForScope(address operator, bytes32 scope, bool approved) external;
    function isApprovedForScope(address owner, address operator, bytes32 scope) external view returns (bool);
}

Scope Metadata JSON Schema

This schema allows for localization and human-readable scope metadata.

{
  "title": "Scope Metadata",
  "type": "object",
  "required": ["name"],
  "properties": {
    "name": {
      "type": "string",
      "description": "Identifies the scope in a human-readable way."
    },
    "description": {
      "type": "string",
      "description": "Describes the scope to allow users to make informed approval decisions."
    },
    "localization": {
      "type": "object",
      "required": ["uri", "default", "locales"],
      "properties": {
        "uri": {
          "type": "string",
          "description": "The URI pattern to fetch localized data from. This URI should contain the substring {locale}."
        },
        "default": {
          "type": "string",
          "description": "The locale of the default data within the base JSON."
        },
        "locales": {
          "type": "array",
          "description": "The list of locales for which data is available."
        }
      }
    }
  }
}

Method Behaviors

• Implementations MAY define a fixed or dynamic set of scopes.
• Scopes can be used to group token IDs by region, type, or any custom logic.
• The setApprovalForScope function MUST emit the ApprovalForScope event.
• Adding or removing IDs from a scope MUST emit the corresponding events.
• The scopeUri function SHOULD return a valid URI for scope metadata, or an empty string if not available.

Localization

Metadata localization should be standardized to increase presentation uniformity across all languages. As such, a simple overlay method is proposed to enable localization. If the metadata JSON file contains a localization attribute, its content may be used to provide localized values for fields that need it. The localization attribute should be a sub-object with three attributes: uri, default and locales. If the string {locale} exists in any URI, it MUST be replaced with the chosen locale by all client software.

Rationale

CBC-1761 generalizes approval mechanisms for multi-token contracts, enabling safer and more flexible operator permissions. By supporting scopes, users can delegate control over specific assets without exposing their entire portfolio, and developers can build more granular access control systems for games, enterprises, and asset platforms.

Metadata JSON

The Scope Metadata JSON Schema was added in order to support human-readable scope names and descriptions in more than one language.

Security Considerations

• Implementers must ensure that scope assignment and approval logic is correct and cannot be bypassed.
• Scopes should be clearly defined and documented to avoid user confusion.
• Metadata URIs should be immutable or versioned to prevent tampering.
• Access control and upgradability best practices should be followed.

References

• JSON Schema

Copyright

Copyright and related rights waived via CC0.