ERC-7818 — Expirable ERC-20

Back to DeFi Building Blocks

ERC-7818: Expirable Tokens

Tokens that expire after a configured duration: airdrops that must be claimed within 30 days, prepaid credits, gift cards, time-bounded rewards. ERC-7818 extends ERC-20 with per-batch expiry tracking — each mint creates a "lot" whose balance becomes inaccessible after its expiration.

Required Interface (Highlights)

function balanceOfAtEpoch(uint256 epoch, address account) external view returns (uint256);
function currentEpoch() external view returns (uint256);
function expirationDuration() external view returns (uint256);

Neo Equivalent

The Neo C# port tracks balances per-epoch in storage. On each transfer, expired lots are skipped; expired balance is effectively burned. Epochs are derived from Runtime.Time / duration.

Live on Neo TestNet

Both implementations deployed on Neo N3 TestNet.

Implementation	TestNet Address	Contract Hash
Solidity (neo-solc)	NfRgrtEfpNb3KCfM33snwzcEBJpAPbFy3F	0xfcaaf98f…a8c6564d
Neo C# (nccs)	NMvFiMjyPN3SVQDhPxGcmDM1F1axhMZP3D	0xcb1b0441…a6ae56e0

Verified: token symbol and decimals. Both contracts track per-epoch balances (epoch derived from block.timestamp / duration or Runtime.Time / duration); balance reads sum the non-expired epoch range. docs/standards-mirror/deployments/erc-7818/.

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

contract ExpirableToken {
    uint256 public immutable epochDuration;        // seconds
    uint256 public immutable retentionEpochs;       // expire after N epochs

    // (account, epoch) -> balance
    mapping(address => mapping(uint256 => uint256)) public balanceAtEpoch;
    mapping(address => uint256) public oldestEpoch;

    event Transfer(address indexed from, address indexed to, uint256 value);
    event Expired(address indexed account, uint256 epoch, uint256 amount);

    constructor(uint256 dur, uint256 retention) {
        epochDuration   = dur;
        retentionEpochs = retention;
    }

    function currentEpoch() public view returns (uint256) {
        return block.timestamp / epochDuration;
    }

    function balanceOf(address a) public view returns (uint256 total) {
        uint256 cur = currentEpoch();
        uint256 from = cur >= retentionEpochs ? cur - retentionEpochs + 1 : 0;
        for (uint256 i = from; i <= cur; ++i) total += balanceAtEpoch[a][i];
    }

    function mint(address to, uint256 amount) external {
        balanceAtEpoch[to][currentEpoch()] += amount;
        emit Transfer(address(0), to, amount);
    }

    function transfer(address to, uint256 amount) external returns (bool) {
        uint256 remaining = amount;
        uint256 cur = currentEpoch();
        uint256 from = cur >= retentionEpochs ? cur - retentionEpochs + 1 : 0;
        for (uint256 i = from; i <= cur && remaining > 0; ++i) {
            uint256 bal = balanceAtEpoch[msg.sender][i];
            uint256 take = bal < remaining ? bal : remaining;
            balanceAtEpoch[msg.sender][i] -= take;
            balanceAtEpoch[to][i]         += take;
            remaining -= take;
        }
        require(remaining == 0, "insufficient non-expired balance");
        emit Transfer(msg.sender, to, amount);
        return true;
    }
}

using System;
using System.ComponentModel;
using System.Numerics;
using Neo;
using Neo.SmartContract.Framework;
using Neo.SmartContract.Framework.Attributes;
using Neo.SmartContract.Framework.Native;
using Neo.SmartContract.Framework.Services;

namespace R3E.Examples;

[DisplayName("ExpirableToken")]
[ContractPermission("*", "*")]
[SupportedStandards(NepStandard.Nep17)]
public class ExpirableToken : SmartContract
{
    private const byte Prefix_BalanceAtEpoch = 0x01;  // owner+epoch -> amount
    private static readonly byte[] DurationKey  = { 0xA0 };
    private static readonly byte[] RetentionKey = { 0xA1 };

    [DisplayName("Transfer")]
    public static event Action<UInt160, UInt160, BigInteger> OnTransfer;
    [DisplayName("Expired")]
    public static event Action<UInt160, BigInteger, BigInteger> OnExpired;

    public static BigInteger CurrentEpoch()
    {
        var dur = (BigInteger)(Storage.Get(Storage.CurrentContext, DurationKey) ?? ByteString.Empty);
        return Runtime.Time / 1000 / dur;
    }

    public static BigInteger BalanceOf(UInt160 owner)
    {
        var ret = (BigInteger)(Storage.Get(Storage.CurrentContext, RetentionKey) ?? ByteString.Empty);
        var cur = CurrentEpoch();
        var from = cur >= ret ? cur - ret + 1 : 0;
        BigInteger total = 0;
        for (var i = from; i <= cur; i++)
            total += BalanceAtEpoch(owner, i);
        return total;
    }

    public static BigInteger BalanceAtEpoch(UInt160 owner, BigInteger epoch)
    {
        var key = new byte[] { Prefix_BalanceAtEpoch }
            .Concat(owner).Concat((ByteString)epoch.ToByteArray());
        return (BigInteger)(Storage.Get(Storage.CurrentContext, key) ?? ByteString.Empty);
    }

    public static void Mint(UInt160 to, BigInteger amount)
    {
        if (!Runtime.CheckWitness(GetAdmin())) throw new Exception("admin only");
        var epoch = CurrentEpoch();
        var prev  = BalanceAtEpoch(to, epoch);
        SetBalance(to, epoch, prev + amount);
        OnTransfer(UInt160.Zero, to, amount);
    }

    public static bool Transfer(UInt160 from, UInt160 to, BigInteger amount, object data)
    {
        if (!Runtime.CheckWitness(from)) throw new Exception("no authorization");
        var ret = (BigInteger)(Storage.Get(Storage.CurrentContext, RetentionKey) ?? ByteString.Empty);
        var cur = CurrentEpoch();
        var fromEpoch = cur >= ret ? cur - ret + 1 : 0;
        var remaining = amount;

        for (var i = fromEpoch; i <= cur && remaining > 0; i++)
        {
            var bal = BalanceAtEpoch(from, i);
            if (bal == 0) continue;
            var take = bal < remaining ? bal : remaining;
            SetBalance(from, i, bal - take);
            SetBalance(to,   i, BalanceAtEpoch(to, i) + take);
            remaining -= take;
        }
        if (remaining > 0) throw new Exception("insufficient non-expired balance");
        OnTransfer(from, to, amount);
        return true;
    }

    private static void SetBalance(UInt160 owner, BigInteger epoch, BigInteger value)
    {
        var key = new byte[] { Prefix_BalanceAtEpoch }
            .Concat(owner).Concat((ByteString)epoch.ToByteArray());
        if (value == 0) Storage.Delete(Storage.CurrentContext, key);
        else            Storage.Put(Storage.CurrentContext, key, value);
    }

    public static void _deploy(object data, bool update)
    {
        if (update) return;
        var args = (object[])data;
        Storage.Put(Storage.CurrentContext, DurationKey,  (BigInteger)args[0]);
        Storage.Put(Storage.CurrentContext, RetentionKey, (BigInteger)args[1]);
    }

    private static UInt160 GetAdmin() => (UInt160)"0x0000000000000000000000000000000000000000";
}