Token Lifecycle Metadata Standard

Token Lifecycle Metadata Standard

Abstract

This CIP defines standard key-value metadata fields tokenExpiration and tradingStop for controlling token usability over time. These metadata keys help developers, exchanges, and auditors enforce lifecycle logic such as halting trading or blocking transfers after expiration. In tokenized systems, especially real-world assets (RWA), tokens may need expiration conditions based on legal or operational constraints. This CIP introduces two optional metadata fields: tokenExpiration (the date after which tokens become unusable) and tradingStop (the date after which exchanges should stop listing the asset). These values are stored as compact Unix timestamps in a key-value metadata store, such as defined in CIP-KV-Metadata.

Motivation

Real-world tokenized instruments often have lifecycles. For example:

• A bond may mature and must not be tradable afterward.
• A compliance-based token may be invalid beyond a certain date.
• A fund share may end its subscription window.

Today, most smart contracts do not provide built-in support for such expiration logic, requiring custom development. This standard proposes consistent metadata keys for enforcing and signaling such behavior.

Specification

Key Definitions

tokenExpiration

• Purpose: Specifies the Unix timestamp after which the token is considered expired.
• Format: Stringified Unix timestamp, e.g. "1719878400" for 2024-07-02.
• Behavior: On-chain enforcement recommended. After this timestamp, transfers and burns should be disabled.

tradingStop

• Purpose: Specifies the last date exchanges should allow token trading.
• Format: Stringified Unix timestamp, e.g. "1719705600" for 2024-06-30.
• Behavior: Informational. Intended for off-chain enforcement by exchanges or trading platforms.

Example Values

"tokenExpiration": "1719878400"
"tradingStop": "1719705600"

These values should be stored in the KV metadata registry of the token smart contract, e.g.:

setValue("tokenExpiration", "1719878400");
setValue("tradingStop", "1719705600");
sealKey("tokenExpiration");
sealKey("tradingStop");

Recommended On-Chain Enforcement

Token contracts should add a modifier such as:

modifier notExpired() {
    string memory expStr = kv.getValue("tokenExpiration");
    require(bytes(expStr).length > 0, "No expiration set");
    uint256 expiry = parseUint(expStr);
    require(block.timestamp < expiry, "Token expired");
    _;
}

Apply to:

• transfer()
• transferFrom()
• burn() (if applicable)

If tokenExpiration is not set, transfers should proceed as normal.

Exchange and DEX Guidance

• tradingStop is intended as a signal to centralized exchanges to halt listings or order books.
• tokenExpiration may be read off-chain or enforced via token logic to prevent post-maturity movement.

Timestamp Format

• Use standard Unix epoch time (seconds since 1970).
• To reduce size, truncate right digits (e.g. to nearest day or hour) if high precision is unnecessary.
• Example: "1719878400" = 2024-07-02 00:00:00 UTC

Backward Compatibility

This metadata format is compatible with:

• CIP-KV-Metadata standard (on-chain key-value)
• CBC-20 and CBC-721 smart contracts
• EVM and non-EVM chains using Unix timestamp logic

Security Considerations

• If tokenExpiration is used, it should be sealed via sealKey() to prevent tampering.
• Frontends should handle expired tokens gracefully and avoid exposing transfer UI.
• Incorrect timestamps may cause false lockouts or trading issues.

Conclusion

The Token Lifecycle Metadata Standard provides a standardized approach to managing token expiration and trading stop dates in Core Blockchain applications. Its adoption can enhance security and compliance in tokenized asset systems.

References

• Test Suite: TokenWithExpiration.t.sol Solidity test file containing unit tests for the TokenWithExpiration contract, verifying correct handling of token expiration logic and related behaviors.

Copyright

Copyright and related rights waived via CC0.