Forensic Token (Forest)

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 depth/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 depth, 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 `0xa4afd005`.
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);
}

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 Events emitted:

• TokenCreated(0x1A…, 0x1A…, address(0))
• TransferSingle(operator, address(0), Alice, 0x1A…, 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 Events emitted:

• TokenSpent(0x0A…, 0x0A…, 50)
• TokenCreated(0x0A…, 0x1A, Alice)
• TransferSingle(operator, Alice, address(0), 0x0A…, 50)
• TransferSingle(operator, address(0), Bob, 0x1A…, 50)

Full Spend Events emitted:

• TokenSpent(0x0A…, 0x0A…, 100)
• TokenCreated(0x0A…, 0x01A…, Alice)
• TransferSingle(operator, Alice, address(0), 0x0A…, 100)
• TransferSingle(operator, address(0), Bob, 0x1A…, 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.

Partial Burn Events emitted:

• TokenSpent(0xFF…, 0x2A…, 50)
• TransferSingle(operator, Alice, address(0), 0x2A…, 50)

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.

Full Burn Events emitted:

• TokenSpent(0xFF…, 0x2A…, 100)
• TransferSingle(operator, Alice, address(0), 0x2A…, 100)

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 depth 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 multiple tokens into a new id, all input tokens MUST share the same root. The resulting lineage is defined by selecting the input token with the greatest depth as the new parent, breaking any ties by choosing the first token listed in the input array. The depth of the new token is then set to the selected parent’s depth plus one.
• 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 depth). 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 depth 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

This timeframe is orders of magnitude longer than the current known age of the universe (≈ 1.38 × 10¹⁰ years). Therefore, limiting the depth 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 depth 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-Depth 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 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 depth 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

For reference implementation can be found here,

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 depths in a single transaction by passing a pre-computed bitmask.

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

Each bucket covers 256 consecutive depths. A single uint256 storage slot represents

depths bucket^256 to (bucket + 1)^256 - 1.

Freezing a depth 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,
        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);
    }
}

Security Considerations

Denial of Service (DoS) via Unbounded Loops

When executing operations such as safeBatchTransferFrom or merging multiple tokens, the contract must iterate over arrays of token IDs. If these arrays are arbitrarily large, the transaction may exceed the network’s block gas limit, causing the transaction to revert and temporarily locking the assets. Contract implementations and interacting decentralized applications (dApps) must enforce strict array length bounds (e.g., maximum batch limits) to prevent out-of-gas (OOG) attack vectors.

Storage Overhead and Dust Accumulation

Because forest represents assets as discrete nodes rather than aggregated account balances, active ledgers will continuously generate new token structs. This naturally leads to higher state storage consumption compared to standard fungible tokens. If a malicious actor spams an account with fractional micro-transactions, it could inflate the DAG and make subsequent batch-spending prohibitively expensive for the victim. To mitigate state bloat, implementations should consider establishing minimum transfer thresholds (dust limits) or restricting decimal precision to prevent unnecessary state fragmentation.

Lineage Contamination during Merges

If a custom implementation allows cross-DAG merging (combining tokens with different root properties), the resulting merged token will inextricably link the histories of both inputs. Wallet interfaces and smart contract routers must exercise extreme caution when aggregating inputs to fulfill a payment. Blindly merging tokens to optimize gas fees—as is common in standard UTXO wallets—may inadvertently contaminate a clean asset with the compliance risk profile of a tainted asset. Client applications should partition unspent tokens by their root identifiers to maintain lineage hygiene.

Public Graph Exposure

Forest provide transparent forensic auditability. Consequently, the parent-child linkages explicitly map the flow of funds in plaintext on the public ledger. While user addresses remain pseudonymous, the asset graph is trivial for third-party observers to trace. Implementers deploying to permissionless networks must operate under the assumption that all token derivation paths are public. Any requirements for transactional confidentiality must be handled at the application layer or via secondary privacy protocols.

Copyright

Copyright and related rights waived via CC0.