ERC-8047: Forensic Token (Forest)

A DAG-based token enabling hierarchical traceability and efficient enforcement for compliant digital assets.

Abstract

Forensic Token (Forest) is a directed acyclic graph (DAG) inspired token model designed to enhance traceability and regulatory compliance in digital currency or e-Money systems. By introducing hierarchical token tracking, it enables efficient enforcement on any token linked to suspicious activity with level/root. Enforcement actions, such as freezing specific tokens or partitioning all tokens with relational links, are optimized to operate at $O(1)$ complexity.

Motivation

The Central Bank Digital Currency and Private Money concept aim to utilize the advantages of Blockchain or Distributed Ledger Technology that provide immutability, transparency, and security, and it adopts smart contracts, which play a key role in creating programmable money. However, technology itself gives an advantage and eliminates the ideal problem of compliance with the regulator and the Anti-Money Laundering and Countering the Financing of Terrorism (AML/CFT) standard, but it does not seem practical to be done in the real world and is not efficiently responsible for the financial crime or incidents that occur in the open network of economics.

Financial crime incident response actions, like freezing accounts or funds, typically necessitate further analysis to pinpoint illicit transactions. This process is off-chain; it can be slow and inefficient. Many existing solutions focus primarily on prevention by attempting to predict bad actors in advance; however, human behavior changes over time, sometimes immediately, especially during periods of economic stress, which may make such approaches unreliable.

Therefore, preventive controls alone cannot fully eliminate bad actors, an inevitable risk in open financial systems. Rather than attempting to predict malicious behavior, there is a need for systems that can respond to incidents faster and more precisely once they occur. The Forensic Token (Forest) is designed to address this need by providing native, on-chain traceability and enforcement at the token level, enabling targeted actions that reduce operational metrics such as Mean Time To Resolve (MTTR) and Mean Time To Fix (MTTF) while preserving on-chain programmability.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Compatible implementations MUST implement the IERC8047 interface and MUST inherit from ERC-1155 and ERC-5615 interfaces. All functions defined in the interface MUST be present and all function behavior MUST meet the behavior specification requirements below.

// 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 level;
        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) level of the DAG that a given token belongs to.
     * @param id The ID of the token.
     * @return uint256 The latest DAG level for the token.
     */
    function latestDAGLevelOf(uint256 id) external view returns (uint256);

    /**
     * @notice Retrieves the level of token within its DAG.
     * @param id The ID of the token.
     * @return uint256 The level of the token in the DAG.
     */
    function levelOf(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);
}

Behavior Specification

Minting

• In the interface does not define an explicit mint function. A mint operation is identified by intent: any operation that creates a new token, thereby adding to the total circulating supply, is considered a mint. Implementations MAY expose a mint function or integrate minting logic within another operation, provided the resulting token satisfies the properties defined below.
• The value MUST NOT be zero. If value is zero, the mint operation MUST revert.
• When minting a token, the id MUST NOT be supplied by the minter; the id MUST be generated via a contract-side mechanism. See Contract-side ID Generation for the reasoning behind this requirement.
• When minting a token, the root property of the new token MUST be set to its own id and the parent property of the new token MUST be set to zero to explicitly indicate that the token serves as the root of a new DAG.
• The event TokenCreated MUST be emitted when the minting token operation is successful.
• The TokenCreated event MUST be emitted with root set to zero when minting a new root token, enabling off-chain indexers to identify and enumerate all DAG origins by filtering on root equal to zero.

Example Minting Scenario

• Scenario when a new token is created without a parent. The resulting token serves as the root of a new DAG.

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

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

• Scenario when the token is spent, a new child token is created. The parent token is either mutated partial spend or full spend.

  Partial Spend
  ┌───────────────────┐                ┌───────────────────┐
  │  Token #A1        │                │  Token #A1        │
  │  root   = #A1     │                │  root   = #A1     │
  │  parent = 0       │   spend 30     │  parent = 0       │
  │  value  = 100     │  ──────────►   │  value  = 70      │
  │  owner  = alice   │                │  owner  = alice   │
  │  level  = 0       │                │  level  = 0       │
  └───────────────────┘                └───────────────────┘
                                                │
                                                ▼
                                       ┌───────────────────┐
                                       │  Token #A2        │
                                       │  root   = #A1     │
                                       │  parent = #A1     │
                                       │  value  = 30      │
                                       │  owner  = bob     │
                                       │  level  = 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   │
  │  level  = 0       │                │  level  = 0       │
  └───────────────────┘                └───────────────────┘
                                                │
                                                ▼
                                       ┌───────────────────┐
                                       │  Token #A2        │
                                       │  root   = #A1     │
                                       │  parent = #A1     │
                                       │  value  = 100     │
                                       │  owner  = bob     │
                                       │  level  = 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)

Burning

• The interface does not define an explicit burn function. A burn operation is identified by intent: any operation that removes value from the total circulating supply by reducing a token’s value is considered a burn. Implementations MAY expose a burn function or integrate burning logic within another operation, provided the resulting state satisfies the properties defined below.
• Burning a token is a soft delete operation. The token id MUST NOT be removed from the DAG. Instead, its value MUST be reduced by the burn amount (e.g., a token with a value of 1000 burned by 1000 results in a value of zero — the token id remains in the DAG with its full lineage intact).
• The burned token MUST NOT transfer ownership to the zero address nor create a new token to the zero address.
• The TokenSpent event MUST be emitted when the burning operation is successful.

Example Burning Scenario

• Scenario partial burn, the token’s value is reduced by the burn amount. The token remains in the DAG with its remaining value.

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

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

• Scenario full burn, the token’s value is reduced to zero. The token id remains in the DAG with its lineage intact but is no longer spendable.

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

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

Existence

• To ensure conformance with ERC-5615, the exists function MUST return true for any id that has been created, even if its value is zero. Implementations MUST determine existence by verifying that the root of the id is not zero. Checking the token’s value MUST NOT be used as an existence check, as a burned token retains its id in the DAG with a value of zero. See Soft Delete and Forensic Persistence for the reasoning behind this requirement.

Spending

• The safeTransferFrom MUST verify that the id exists. If it does not, the function MUST revert.
• The safeTransferFrom MUST revert if the from address is equal to the to address.
• The from MUST be the owner of the id or an approved operator.
• The value to be spent MUST NOT be zero.
• The value to be spent MUST NOT exceed the value of the id. If it does, the function MUST revert.
• The safeTransferFrom function MUST mint a new id as a child of the id being spent. The new id MUST have its parent set to the id that was spent and its level MUST be incremented by one relative to the parent.
• When value is less than the token’s current value, the operation is considered a partial spend. The parent token’s value MUST be reduced by the spent value.
• When value is equal to the token’s current value, the operation is considered a full spend. The parent token’s value MUST be set with zero.
• To maintain compatibility with ERC-1155, safeTransferFrom MUST emit two TransferSingle events on full spend to reflect the parent–child token behavior.
  • One for burning the parent token TransferSingle(operator, from, address(0), id, value).
  • One for minting the new child token TransferSingle(operator, address(0), to, newId, value).
• On partial spend, safeTransferFrom MUST emit two TransferSingle events. The first reflects the reduction of the parent token’s value. The parent token remains in the DAG with a reduced value.
  • One for reducing the parent token’s value TransferSingle(operator, from, address(0), id, value).
  • One for minting the new child token TransferSingle(operator, address(0), to, newId, value).
• Similarly, safeBatchTransferFrom MUST emit two TransferBatch events, preserving token order.
  • First, for burning or reducing all parent tokens in the batch, MUST follow the order provided by the input ids array.
  • Second, for minting all corresponding child tokens, they MUST match the same order of ids as the parent batch.
• The TokenSpent event MUST be emitted with the spent amount whenever the token is spent, whether partial or full.
• The TokenCreated event MUST be emitted whenever a new child token is successfully created.

Merging

• To maintain compatibility with standard indexers and wallets that support ERC-1155, implementations MUST emit the standard TransferBatch event transferring the consumed ids from the owner to the zero address to reflect their consumption. Additionally, a standard TransferSingle and TokenCreated event MUST be emitted for the newly minted merged token id.

• To merge two or more ids into a new id, the default merging operation REQUIRE that all tokens be part of the same DAG to maintain a clean lineage (i.e., share the same root). The level and parent of the new id from merging will be formalized as

  \(k = \max_{i}(level_i), \quad i \in ids\) \(parent_k = ids\bigl[\min\{i : level_i = k\}\bigr]\)

  \(newTokenIdLevel = k + 1\) \(newTokenIdParent = parent_k\)

• The TokenMerged event MUST be emitted, including all ids involved in the merge, when the merging operation is successful.
• Implementations MAY allow merging tokens from different root. If a merge occurs across different DAGs, the implementation MUST define a deterministic rule for assigning the root of the new token. (e.g., inheriting the root of the token with the highest value or the lowest level). Implementers MUST carefully consider the consequences of cross-DAG merging, as it combines previously independent asset lineages. This makes the lineage less clean and complicates forensic tracking, as enforcement actions or risk profiles associated with any of the original root will now propagate to the newly merged token id. Before executing a cross-DAG merge, implementations MAY enforce rules ensuring sufficient transaction confirmations or adequate confidence levels. Furthermore, when signaling this custom behavior via the TokenMerged event, implementations MUST use a mergeType flag strictly greater than zero, as zero is reserved exclusively for the default same DAG merge operation.
• The validation step MAY be implemented before the merging logic executes. This leaves room for implementation-specific rules, such as gatekeeper, limit amount, etc.

URI JSON Schema

In this proposal, each token has a unique id to track its movement in the DAG (like serial numbers), but all tokens representing the same asset share a single metadata URI. This reflects the fungible nature of the asset (like fiat currency).

• All tokens of the same asset MUST reference the same URI, regardless of their individual id.
• Implementations SHOULD follow the JSON Schema definition provided below for consistency across client implementations.

{
  "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"]
}

A complete JSON Schema reference for ERC-8047 metadata is provided below for validation and implementation guidance.

{
  "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/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"
    }
  }
}

Rationale

Contract-side ID Generation

The token ID is generated dynamically by the contract-side upon execution, rather than supplied by the caller. Because employs a Unspent Transaction Output (UTXO)-like mechanism where each transfer effectively spends an existing token and mints a new one to continue the DAG lineage, allowing caller-supplied IDs for these newly spawned tokens introduces critical attack vectors. Such vulnerabilities include ID collisions, unauthorized overwriting of lineage records, or root impersonation. Enforcing deterministic, contract-side ID generation at the time of the call guarantees global uniqueness and preserves the structural integrity of the lineage.

Transaction Flow Consistency

Unlike the UTXO model, the Forest architecture permits stateful mutations of existing tokens while enforcing strict parent–child lineage. Tokens support fractional, iterative expenditures until depletion. By natively embedding parent references within each token, the architecture optimizes for reverse topological traversal. This enables highly efficient back-to-root queries—isolating a specific token’s lineage up to its origin without the computational overhead of full DAG traversal. This continuous topology inextricably links all child nodes back to their roots, guaranteeing deterministic forensic traceability that traditional, aggregated account-based standards like ERC-20 or ERC-3643 fundamentally lack this granular traceability, as they obfuscate individual token flows into aggregated account balances.

Reverse Topological Ordering of Tokens

The forest token-based model it natively supports reverse topological traversal. Each token stores a reference to its parent token, allowing to efficiently iterate from any given token back to its root token of the DAG. This back-to-root traversal differs from a full DAG traversal. It only follows the lineage of a specific token ID up to its root, rather than visiting all tokens in the DAG.

Variable Packing

The property level returns uint96 as this offers the maximum possible precision that fits within the same storage slot as the owner address. Since an address occupies 160 bits, exactly 96 bits remain available in the 256 bits word. Utilizing uint96 ensures zero wasted space.

From a functional perspective, uint96 allows for a tree depth of , which is for all practical purposes infinite. Even in an extreme scenario on a high-performance network or Layer 2 with a 250ms block time that produces 4 blocks per second, assuming a transaction increases the tree depth every single block

\(\text{Network block time} = 250 \text{ ms}\) \(\text{Seconds per year} \approx 31{,}536{,}000 \text{ seconds}\) \(\text{Blocks per year} = 4 \times 31{,}536{,}000 = 126{,}144{,}000 \text{ blocks}\) \(\text{Years to overflow} = \frac{2^{96}}{126{,}144{,}000} = \frac{79{,}228{,}162{,}514{,}264{,}337{,}593{,}543{,}950{,}336}{126{,}144{,}000} \approx 6.2 \times 10^{20} \text{ years}\)

This timeframe is orders of magnitude longer than the current known age of the universe ($\approx 1.38 \times 10^{10} \text{ years}$). Therefore, limiting the level to uint96 to achieve storage packing imposes no realistic constraint on the system’s longevity or throughput.

Soft Delete and Forensic Persistence

Tokens are never removed from the DAG when it’s create. Removing a burned token would destroy its lineage record, breaking the forensic chain between parent and child tokens. Any enforcement action applied to a root or level must remain traceable to all tokens that were ever part of that DAG family, including those that have been fully spent. Hard deletion is therefore incompatible with the forensic guarantees this standard provides.

Multi-Level Compliance Enforcement

Traditional systems are enforced at the account level. This often means freezing an entire wallet just to stop one bad transaction, which unfairly locks up a user’s legitimate funds. Forest solves this by applying rules to both the account and the individual tokens. It works like pruning a tree rather than chopping it down. This precision allows authorities to target only the specific illicit assets while leaving the rest of the user’s portfolio untouched and fully operational.

Constant-Time Enforcement

The constant-time enforcement (i.e., $O(1)$ complexity) claim refers to the cost of applying an enforcement action relative to the size of the DAG, total token count, or number of tokens sharing the same root. Tokens sharing the same root form a single DAG family. Enforcement actions applied at the root or level propagate implicitly to all linked tokens within that family without iteration. Regardless of how large the DAG grows, enforcement cost remains constant. For a reference implementation, see Token Policy Enforcement (TPEn).

Spendable Balance via off-chain

On-chain iteration to retrieve spendable balance can be gas-intensive and inefficient, especially for large DAGs or multiple sets of DAGs. To address this, the current spendable balance of account can be determined off-chain by deploying a service that subscribes to events emitted by the contract. This service calculates the spendable balance by reconciling the account’s total balance of with any tokens that have been frozen or restricted due to hierarchical or forensic rules, providing an accurate representation of the amount available for spend.

Backwards Compatibility

This standard is fully compatible with ERC-1155 and ERC-5615.

Reference Implementation

Token Policy Enforcement (TPEn)

The following abstract contract provides a reference implementation of the TPEn. It demonstrates the gas-optimized logic required to evaluate and apply topological DAG quarantines using 256-bit storage packing and bitwise operations. Furthermore, this bucket-based design natively enables mass-quarantine capabilities, laying the groundwork for regulators to simultaneously freeze or unfreeze up to 256 distinct topological levels in a single transaction by passing a pre-computed bitmask.

Each DAG level maps to a 256-bit storage bucket and a specific bit position within that bucket using bitwise operations:

Each bucket covers 256 consecutive levels. A single uint256 storage slot represents
levels bucket^256 to (bucket + 1)^256 - 1.

Freezing a level sets the corresponding bit to 1 via bitwise OR. Unfreezing sets it to 0 via bitwise AND NOT. Checking freeze status reads the bit via bitwise AND.

// 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,
        LEVEL,
        DISCRETE
    }

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

    mapping(uint256 => Policy) private _policies;

    error TokenFrozen();
    error TokenNotFrozen();
    error LevelFrozen();
    error LevelNotFrozen();
    error ConflictingBounds();
    error InvalidUnfreezeTypes();
    error BoundNotSet();

    event FrozenToken(uint256 indexed tokenId);
    event FrozenBefore(uint256 indexed root, uint256 level);
    event FrozenAfter(uint256 indexed root, uint256 level);
    event FrozenLevel(uint256 indexed root, uint256 level);

    event UnfrozenToken(uint256 indexed tokenId);
    event UnfrozenBefore(uint256 indexed root, uint256 level);
    event UnfrozenAfter(uint256 indexed root, uint256 level);
    event UnfrozenLevel(uint256 indexed root, uint256 level);

    /**
     * @notice Calculates the 256-bit storage bucket and specific bit index for a given DAG level.
     * @dev Uses pure bitwise operations in assembly for gas optimization.
     * @param level The chronological depth (Y-axis) of the token in the DAG.
     * @return bucket The exact 256-level chunk where the state is stored.
     * @return bitIndex The specific bit position (0-255) within that bucket.
     */
    function calcTokenBucketAndBitIndex(uint256 level) private pure returns (uint256 bucket, uint256 bitIndex) {
        assembly ("memory-safe") {
            // right shift by 8 bits (equivalent to level / 256)
            bucket := shr(8, level)
            // bitwise AND 255 (equivalent to level % 256)
            bitIndex := and(level, 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 level 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 level) public view returns (bool, FREEZE_TYPES) {
        Policy storage policy = _policies[root];

        // boundary checks
        uint128 beforeLevel = policy.beforeLevel;
        uint128 afterLevel = policy.afterLevel;

        if (beforeLevel != 0 && level <= beforeLevel) return (true, FREEZE_TYPES.LOWER_BOUND);
        if (afterLevel != 0 && level >= afterLevel) return (true, FREEZE_TYPES.UPPER_BOUND);

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

        // 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 level are frozen.
     * @dev Reverts if the requested level overlaps with an existing upper bound.
     * @param root The DAG transaction family ID.
     * @param level The DAG depth limit.
     */
    function freezeTokenBefore(uint256 root, uint256 level) public virtual {
        Policy storage policy = _policies[root];
        if (policy.afterLevel != 0 && level >= policy.afterLevel) revert ConflictingBounds();

        policy.beforeLevel = uint128(level);
        emit FrozenBefore(root, level);
    }

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

        policy.afterLevel = uint128(level);

        emit FrozenAfter(root, level);
    }

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

        policy.beforeLevel = 0;

        emit UnfrozenBefore(root, level);
    }

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

        policy.afterLevel = 0;

        emit UnfrozenAfter(root, level);
    }

    /**
     * @notice Applies an O(1) bitmask quarantine to a specific topological level.
     * @dev Reverts if the targeted level is already frozen to prevent redundant gas spend and duplicate events.
     * @param root The DAG transaction family ID.
     * @param level The exact DAG depth to freeze.
     */
    function freezeLevel(uint256 root, uint256 level) public virtual {
        (uint256 bucket, uint256 bitIndex) = calcTokenBucketAndBitIndex(level);
        // 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 LevelFrozen();
        // apply the bitwise OR and write back to storage.
        _policies[root].bitmasks[bucket] = currentMask | targetBit;

        emit FrozenLevel(root, level);
    }

    /**
     * @notice Removes a specific topological level from the bitmask quarantine.
     * @dev Reverts if the targeted level is not currently frozen to prevent redundant gas spend.
     * @param root The DAG transaction family ID.
     * @param level The exact DAG depth to unfreeze.
     */
    function unfreezeLevel(uint256 root, uint256 level) public virtual {
        (uint256 bucket, uint256 bitIndex) = calcTokenBucketAndBitIndex(level);
        // 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 LevelNotFrozen();
        // apply the bitwise AND NOT and write back to storage.
        _policies[root].bitmasks[bucket] = currentMask & ~targetBit;

        emit UnfrozenLevel(root, level);
    }

    /**
     * @notice Freezes a specific discrete token ID.
     * @param root The DAG transaction family ID.
     * @param tokenId The unique identifier of the token.
     * @param level The topological depth of the token.
     */
    function freezeToken(uint256 root, uint256 tokenId, uint256 level) public virtual {
        (bool isFrozen, ) = isTokenFrozen(root, tokenId, level);
        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 level mask.
     * @param root The DAG transaction family ID.
     * @param tokenId The unique identifier of the token.
     * @param level The topological depth of the token.
     */
    function unfreezeToken(uint256 root, uint256 tokenId, uint256 level) public virtual {
        (bool isFrozen, FREEZE_TYPES types) = isTokenFrozen(root, tokenId, level);

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

        updateFreezeToken(root, tokenId, false);
    }
}

Security Considerations

Denial Of Service (DoS)
A potential out-of-gas issue may occur due to the transaction gas limit cap introduced in EIP-7825, Operations such as safeBatchTransferFrom may consume more gas than permitted by the transaction gas limit introduced in EIP-7825, leading to transaction revert. For private networks that do not adopt EIP-7825 the transaction may exceed the block gas limit if the required gas is higher than the network’s configured maximum. To mitigate this, implementations should enforce a maximum limit on the number of input IDs allowed per transaction.

State Growth
The token-based model tracks all assets within the system, formalized as

where:

• $A_{\text{totalSupply}}$: the total supply of the asset in whole units.
• $A_{\text{decimals}}$: the decimal precision of the asset.
• $A_{\text{ids}}$: the maximum number of distinct token IDs required to represent the asset at full decimal precision.

While this ensures precision, high granularity can increase storage needs. Traditional finance often uses simpler decimals (2, 4, or 6) to avoid excessive fragmentation. Adopting similar constraints such as capping decimals or enforcing a minimum token value before spending could help balance granularity with efficiency.

Coin Selection and Risk Propagation
Implementers have the flexibility to design automated coin selection algorithms tailored to user needs, such as First-In-First-Out (FIFO) , Last-In-First-Out (LIFO) or other optimization strategies base on business need e.g. transaction fees optimization. This introduces a risk of account linking, where legitimate and illicit token IDs are combined in a single batch transfer. Because traditional compliance frameworks rely on account-level heuristics, they may incorrectly penalize a user’s creditworthiness due to this association or the presence of isolated frozen tokens. To prevent unwarranted financial exclusion, compliance infrastructure must be updated to derive reputation from Net Spendable Equity (clean assets) rather than the aggregate portfolio state.

Confidentiality and Privacy
Unlike opaque account-based models, this proposal treats every token as a traceable lineage, explicitly prioritizing forensic auditability. By preserving parent-child links on-chain, the protocol exposes the full transaction graph to observers. The proposal itself remains strictly pseudonymous. It tracks the relationships between assets, not the identities of owners, and the core specification stores no Personally Identifiable Information (PII). However, implementations of this standard may differ. Issuers are free to layer identity requirements such as whitelists or Soulbound Tokens (SBT) on top of the base protocol. Therefore, while the data structure is pseudonymous, a specific deployment may enforce real-world identity bindings.

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Sirawit Techavanitch (@MASDXI) <sirawit_tec@live4.utcc.ac.th>, Supache Innet <supachate_inn@utcc.ac.th>, "ERC-8047: Forensic Token (Forest) [DRAFT]," Ethereum Improvement Proposals, no. 8047, October 2025. Available: https://eips.ethereum.org/EIPS/eip-8047.