ERC-8047 - Forensic Token (Forest)

// SPDX-License-Identifier: CC0-1.0
pragma solidity >=0.8.0 <0.9.0;

/**
 * @title ERC-8047 interface
 */

// import "./IERC1155.sol";
// import "./IERC5615.sol";

// The EIP-165 identifier of this interface is `0x8aae36fc`.
interface IERC8047 /**is IERC1155, IERC5615 */ {
    /**
     * @dev Structure representing a token (node) within the Forest DAG.
     */
    struct Token {
        uint256 root;
        uint256 parent;
        uint256 value;
        uint96 depth;
        address owner;
    }

    /**
     * @notice Emitted when a new token is created within a DAG.
     * @param root The root token ID of the DAG to which the new token belongs.
     * @param id The ID of the newly created token.
     * @param from The address that created/minted the token.
     */
    event TokenCreated(
        uint256 indexed root,
        uint256 id,
        address indexed from
    );

    /**
     * @notice Emitted when a token is spent or partially spent.
     * @param root The root token ID of the DAG to which the new token belongs.
     * @param id The ID of the token being spent.
     * @param value The amount of the token that was spent.
     */
    event TokenSpent(
      uint256 indexed root,
      uint256 indexed id,
      uint256 value
    );

    /**
     * @notice Emitted when multiple tokens are successfully merged into a single new token.
     * @param ids The array of original token IDs that were consumed in the merge.
     * @param id The ID of the newly created merged token.
     * @param from The address of the token owner who initiated the merge.
     * @param mergeType A flag indicating the rule set used for the merge.
     * `0` represents the default merge (all tokens from the same DAG).
     * values > 0 are reserved for custom implementations (e.g., cross dags merges).
     */
    event TokenMerged(uint256[] ids, uint256 indexed id, address indexed from, uint8 mergeType);

    /**
     * @notice Retrieves the latest (highest) depth of the DAG that a given token belongs to.
     * @param id The ID of the token.
     * @return uint256 The latest DAG depth for the token.
     */
    function latestDAGDepthOf(uint256 id) external view returns (uint256);

    /**
     * @notice Retrieves the depth of a token within its DAG.
     * @param id The ID of the token.
     * @return uint256 The depth of the token in the DAG.
     */
    function depthOf(uint256 id) external view returns (uint256);

    /**
     * @notice Retrieves the owner of a given token.
     * @param id The ID of the token.
     * @return address The address that owns the token.
     */
    function ownerOf(uint256 id) external view returns (address);

    /**
     * @notice Retrieves the parent token ID of a given token.
     * @param id The ID of the token.
     * @return uint256 The ID of the parent token. Retrieves 0 if the token is a root.
     */
    function parentOf(uint256 id) external view returns (uint256);

    /**
     * @notice Retrieves the root token ID of the DAG to which a given token belongs.
     * @param id The ID of the token.
     * @return uint256 The root token ID of the DAG.
     */
    function rootOf(uint256 id) external view returns (uint256);

    /**
     * @notice Retrieves token detail from given token id.
     * @param id The ID of the token.
     * @return Token struct containing the token's detailed properties.
     */
    function token(uint256 id) external view returns (Token memory);

    /**
     * @notice Retrieves the total value of all tokens currently in circulation.
     * Each token contributes its current `value` to the total.
     * @custom:overloading of {IERC5615.totalSupply}
     * @return uint256 The sum of all token values currently in circulation.
     */
    function totalSupply() external view returns (uint256);
}

        Mint
          │
          ▼
  ┌───────────────────┐
  │  Token #A1        │
  │  root   = #A1     │
  │  parent = 0       │
  │  value  = 100     │
  │  depth  = 0       │
  └───────────────────┘

  Events emitted:
  TokenCreated(root=#A1, id=#A1, from=address(0))
  TransferSingle(operator, address(0), receiver, #A1, 100)

  Partial Spend
  ┌───────────────────┐                ┌───────────────────┐
  │  Token #A1        │                │  Token #A1        │
  │  root   = #A1     │                │  root   = #A1     │
  │  parent = 0       │   spend 30     │  parent = 0       │
  │  value  = 100     │  ──────────►   │  value  = 70      │
  │  owner  = alice   │                │  owner  = alice   │
  │  depth  = 0       │                │  depth  = 0       │
  └───────────────────┘                └───────────────────┘
                                                │
                                                ▼
                                       ┌───────────────────┐
                                       │  Token #A2        │
                                       │  root   = #A1     │
                                       │  parent = #A1     │
                                       │  value  = 30      │
                                       │  owner  = bob     │
                                       │  depth  = 1       │
                                       └───────────────────┘
  Events emitted:
  TokenSpent(#A1, #A1, 30)
  TokenCreated(#A1, #A2, spender)
  TransferSingle(operator, spender, receiver, #A1, 30)
  TransferSingle(operator, zero_address, receiver, #A2, 30)

  Full Spend
  ┌───────────────────┐                ┌───────────────────┐
  │  Token #A1        │                │  Token #A1        │
  │  root   = #A1     │                │  root   = #A1     │
  │  parent = 0       │   spend 100    │  parent = 0       │
  │  value  = 100     │  ──────────►   │  value  = 0       │
  │  owner  = alice   │                │  owner  = alice   │
  │  depth  = 0       │                │  depth  = 0       │
  └───────────────────┘                └───────────────────┘
                                                │
                                                ▼
                                       ┌───────────────────┐
                                       │  Token #A2        │
                                       │  root   = #A1     │
                                       │  parent = #A1     │
                                       │  value  = 100     │
                                       │  owner  = bob     │
                                       │  depth  = 1       │
                                       └───────────────────┘
  Events emitted:
  TokenSpent(#A1, #A1, 100)
  TokenCreated(#A1, #A2, spender)
  TransferSingle(operator, spender, zero_address, #A1, 100)
  TransferSingle(operator, zero_address, receiver, #A2, 100)

  ┌─────────────────────┐                   ┌─────────────────────┐
  │  Token #A1          │                   │  Token #A1          │
  │  root   = #A1       │                   │  root   = #A1       │
  │  parent = 0         │   burn 100        │  parent = 0         │
  │  value  = 1000      │  ──────────────►  │  value  = 900       │
  │  owner  = alice     │                   │  owner  = alice     │
  │  depth  = 0         │                   │  depth  = 0         │
  └─────────────────────┘                   └─────────────────────┘

  Events emitted:
  TokenSpent(#A1, #A1, 100)
  TransferSingle(operator, spender, zero_address, #A1, 100)

  ┌─────────────────────┐                   ┌─────────────────────┐
  │  Token #A1          │                   │  Token #A1          │
  │  root   = #A1       │                   │  root   = #A1       │
  │  parent = 0         │   burn 1000       │  parent = 0         │
  │  value  = 1000      │  ──────────────►  │  value  = 0         │
  │  owner  = alice     │                   │  owner  = alice     │
  │  depth  = 0         │                   │  depth  = 0         │
  └─────────────────────┘                   └─────────────────────┘

  Events emitted:
  TokenSpent(#A1, #A1, 1000)
  TransferSingle(operator, from, zero_address, #A1, 1000)

{
  "title": "Token Metadata",
  "description": "Metadata schema for ERC-8047: Forensic Token (Forest).",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Human-readable name of the asset represented by this token."
    },
    "symbol": {
      "type": "string",
      "description": "Ticker symbol or shorthand identifier for the token."
    },
    "decimals": {
      "type": "integer",
      "description": "Number of decimal places used to display token amounts. For example, 18 means the token amount should be divided by 10^18 to get its user representation."
    },
    "description": {
      "type": "string",
      "description": "Detailed description of the asset represented by this token."
    },
    "image": {
      "type": "string",
      "format": "uri",
      "description": "A URI pointing to an image (MIME type image/*) that visually represents the asset. Recommended image width: 320–1080 pixels; aspect ratio: between 1.91:1 and 4:5."
    },
    "properties": {
      "type": "object",
      "description": "Container for extended metadata such as compliance, traceability, and DAG lineage.",
      "properties": {
        "compliance": {
          "type": "object",
          "description": "Compliance and policy information for the asset.",
          "properties": {
            "issuer": {
              "type": "string",
              "description": "Legal entity responsible for issuing or managing this asset."
            },
            "jurisdiction": {
              "type": "string",
              "description": "Legal jurisdiction or regulatory domain governing this asset."
            },
            "policies": {
              "type": "string",
              "format": "uri",
              "description": "URI linking to AML/CFT, compliance, or risk policy documentation."
            },
            "enforcement_authority": {
              "type": "string",
              "format": "uri",
              "description": "URI to the entity or endpoint responsible for enforcement actions (e.g., freeze, revoke)."
            }
          },
          "required": ["issuer", "policies"]
        }
      },
      "required": ["compliance"]
    }
  },
  "required": ["name", "description", "image", "properties"]
}

{
  "name": "United States Dollar",
  "symbol": "USD",
  "decimals": 18,
  "description": "A compliant, traceable digital representation of the U.S. Dollar using the ERC-8047: Forensic Token (Forest).",
  "image": "https://acmee-finance.invalid/static/assets/images/USD_icon.png",
  "properties": {
    "compliance": {
      "issuer": "Acmee Finance Inc.",
      "jurisdiction": "US-NY",
      "policies": "https://acmee-finance.invalid/policies",
      "enforcement_authority": "https://acmee-finance.invalid/enforcement"
    }
  }
}

// SPDX-License-Identifier: CC0-1.0
pragma solidity >=0.8.0 <0.9.0;

/**
 * @title AbstractTokenPolicyEnforcement (TPEn)
 * @dev Abstract contract for managing O(1) multi-dimensional token quarantines.
 * @notice This contract allows regulators to freeze and unfreeze tokens using topological bounds, bitmasks, and discrete mapping.
 */
abstract contract AbstractTokenPolicyEnforcement {
    enum FREEZE_TYPES {
        NONE,
        LOWER_BOUND,
        UPPER_BOUND,
        DEPTH,
        DISCRETE
    }

    struct Policy {
        // uint128 is enough, since {IERC8047.tokens} store depth with uint92.
        uint128 beforeDepth;
        uint128 afterDepth;
        mapping(uint256 => bool) tokens;
        mapping(uint256 => uint256) bitmasks;
    }

    mapping(uint256 => Policy) private _policies;

    error TokenFrozen();
    error TokenNotFrozen();
    error DepthFrozen();
    error DepthNotFrozen();
    error ConflictingBounds();
    error InvalidUnfreezeTypes();
    error BoundNotSet();

    event FrozenToken(uint256 indexed tokenId);
    event FrozenBefore(uint256 indexed root, uint256 depth);
    event FrozenAfter(uint256 indexed root, uint256 depth);
    event FrozenDepth(uint256 indexed root, uint256 depth);

    event UnfrozenToken(uint256 indexed tokenId);
    event UnfrozenBefore(uint256 indexed root, uint256 depth);
    event UnfrozenAfter(uint256 indexed root, uint256 depth);
    event UnfrozenDepth(uint256 indexed root, uint256 depth);

    /**
     * @notice Calculates the 256-bit storage bucket and specific bit index for a given DAG depth.
     * @dev Uses pure bitwise operations in assembly for gas optimization.
     * @param depth The chronological depth (Y-axis) of the token in the DAG.
     * @return bucket The exact 256-depth chunk where the state is stored.
     * @return bitIndex The specific bit position (0-255) within that bucket.
     */
    function calcTokenBucketAndBitIndex(uint256 depth) private pure returns (uint256 bucket, uint256 bitIndex) {
        assembly ("memory-safe") {
            // right shift by 8 bits (equivalent to depth / 256)
            bucket := shr(8, depth)
            // bitwise AND 255 (equivalent to depth % 256)
            bitIndex := and(depth, 0xFF)
        }
    }

    /**
     * @notice Internal function to update the discrete frozen status of a specific token.
     * @param root The identifier of the DAG transaction family.
     * @param tokenId The unique identifier of the discrete asset.
     * @param freeze The target status (true to freeze, false to unfreeze).
     */
    function updateFreezeToken(uint256 root, uint256 tokenId, bool freeze) private {
        _policies[root].tokens[tokenId] = freeze;
        if (freeze) {
            emit FrozenToken(tokenId);
        } else {
            emit UnfrozenToken(tokenId);
        }
    }

    /**
     * @notice Evaluates if a token is frozen.
     * @param root The DAG transaction family ID.
     * @param tokenId The specific discrete asset token ID.
     * @param depth The topological depth of the token.
     * @return isFrozen Boolean indicating if the token is frozen.
     * @return freezeType The specific freeze type.
     */
    function isTokenFrozen(uint256 root, uint256 tokenId, uint256 depth) public view returns (bool, FREEZE_TYPES) {
        Policy storage policy = _policies[root];

        // boundary checks
        uint128 beforeDepth = policy.beforeDepth;
        uint128 afterDepth = policy.afterDepth;

        if (beforeDepth != 0 && depth <= beforeDepth) return (true, FREEZE_TYPES.LOWER_BOUND);
        if (afterDepth != 0 && depth >= afterDepth) return (true, FREEZE_TYPES.UPPER_BOUND);

        // bitmask check
        (uint256 bucket, uint256 bitIndex) = calcTokenBucketAndBitIndex(depth);
        if ((policy.bitmasks[bucket] & (1 << bitIndex)) != 0) {
            return (true, FREEZE_TYPES.DEPTH);
        }

        // specific token check
        if (policy.tokens[tokenId]) {
            return (true, FREEZE_TYPES.DISCRETE);
        }

        // fallback case
        return (false, FREEZE_TYPES.NONE);
    }

    /**
     * @notice Establishes a continuous lower bound. All tokens at or below this depth are frozen.
     * @dev Reverts if the requested depth overlaps with an existing upper bound.
     * @param root The DAG transaction family ID.
     * @param depth The DAG depth limit.
     */
    function freezeTokenBefore(uint256 root, uint256 depth) public virtual {
        Policy storage policy = _policies[root];
        if (policy.afterDepth != 0 && depth >= policy.afterDepth) revert ConflictingBounds();

        policy.beforeDepth = uint128(depth);
        emit FrozenBefore(root, depth);
    }

    /**
     * @notice Establishes a continuous upper bound. All tokens at or above this depth are frozen.
     * @dev Reverts if the requested depth overlaps with an existing lower bound.
     * @param root The DAG transaction family ID.
     * @param depth The DAG depth limit.
     */
    function freezeTokenAfter(uint256 root, uint256 depth) public virtual {
        Policy storage policy = _policies[root];
        if (policy.beforeDepth != 0 && depth <= policy.beforeDepth) revert ConflictingBounds();

        policy.afterDepth = uint128(depth);

        emit FrozenAfter(root, depth);
    }

    /**
     * @notice Completely lifts the continuous lower bound quarantine for a DAG family.
     * @param root The DAG transaction family ID.
     * @param depth The previous bound depth (logged for off-chain indexing).
     */
    function unfreezeTokenBefore(uint256 root, uint256 depth) public virtual {
        Policy storage policy = _policies[root];
        if (policy.beforeDepth == 0) revert BoundNotSet();

        policy.beforeDepth = 0;

        emit UnfrozenBefore(root, depth);
    }

    /**
     * @notice Completely lifts the continuous upper bound quarantine for a DAG family.
     * @param root The DAG transaction family ID.
     * @param depth The previous bound depth (logged for off-chain indexing).
     */
    function unfreezeTokenAfter(uint256 root, uint256 depth) public virtual {
        Policy storage policy = _policies[root];
        if (policy.afterDepth == 0) revert BoundNotSet();

        policy.afterDepth = 0;

        emit UnfrozenAfter(root, depth);
    }

    /**
     * @notice Applies an O(1) bitmask quarantine to a specific topological depth.
     * @dev Reverts if the targeted depth is already frozen to prevent redundant gas spend and duplicate events.
     * @param root The DAG transaction family ID.
     * @param depth The exact DAG depth to freeze.
     */
    function freezeDepth(uint256 root, uint256 depth) public virtual {
        (uint256 bucket, uint256 bitIndex) = calcTokenBucketAndBitIndex(depth);
        // load the current 256-bit bucket into memory.
        uint256 currentMask = _policies[root].bitmasks[bucket];
        uint256 targetBit = 1 << bitIndex;
        // check if the specific bit is already 1. If yes, revert.
        if ((currentMask & targetBit) != 0) revert DepthFrozen();
        // apply the bitwise OR and write back to storage.
        _policies[root].bitmasks[bucket] = currentMask | targetBit;

        emit FrozenDepth(root, depth);
    }

    /**
     * @notice Removes a specific topological depth from the bitmask quarantine.
     * @dev Reverts if the targeted depth is not currently frozen to prevent redundant gas spend.
     * @param root The DAG transaction family ID.
     * @param depth The exact DAG depth to unfreeze.
     */
    function unfreezeDepth(uint256 root, uint256 depth) public virtual {
        (uint256 bucket, uint256 bitIndex) = calcTokenBucketAndBitIndex(depth);
        // load the current 256-bit bucket into memory.
        uint256 currentMask = _policies[root].bitmasks[bucket];
        uint256 targetBit = 1 << bitIndex;
        // check if the specific bit is already 0. If yes, revert.
        if ((currentMask & targetBit) == 0) revert DepthNotFrozen();
        // apply the bitwise AND NOT and write back to storage.
        _policies[root].bitmasks[bucket] = currentMask & ~targetBit;

        emit UnfrozenDepth(root, depth);
    }

    /**
     * @notice Freezes a specific discrete token ID.
     * @param root The DAG transaction family ID.
     * @param tokenId The unique identifier of the token.
     * @param depth The topological depth of the token.
     */
    function freezeToken(uint256 root, uint256 tokenId, uint256 depth) public virtual {
        (bool isFrozen, ) = isTokenFrozen(root, tokenId, depth);
        if (isFrozen) revert TokenFrozen();

        updateFreezeToken(root, tokenId, true);
    }

    /**
     * @notice Unfreezes a specific discrete token ID.
     * @dev Reverts if the token is locked by a continuous bound or depth mask.
     * @param root The DAG transaction family ID.
     * @param tokenId The unique identifier of the token.
     * @param depth The topological depth of the token.
     */
    function unfreezeToken(uint256 root, uint256 tokenId, uint256 depth) public virtual {
        (bool isFrozen, FREEZE_TYPES types) = isTokenFrozen(root, tokenId, depth);

        if (!isFrozen) revert TokenNotFrozen();
        if (types != FREEZE_TYPES.DISCRETE) revert InvalidUnfreezeTypes();

        updateFreezeToken(root, tokenId, false);
    }
}