ERC-6982 — Default Lockable Tokens

Back to Token Standards

ERC-6982: Default Lockable Tokens

ERC-6982 standardises a lightweight lock state for NFTs: a tokenId can be locked (transfers blocked) or unlocked (transfers allowed), without committing to a specific lock-controller pattern. The collection-wide default lock state is set at deploy; per-token overrides flip individual tokens. Used for:

• Staking — locked while staked, unlocked when withdrawn.
• Escrow — locked during a deal, unlocked on settlement.
• Soulbinding-by-default — collections that mint locked, unlock on redemption (lighter than ERC-5192 / ERC-5484 since the lock can be flipped both ways).
• Lending collateral — locked while collateralising a loan, unlocked on repayment.

ERC-6982 is intentionally narrower than ERC-5192 (binary soulbound) and ERC-6147 (guard delegate). It just exposes the lock-state predicate; the who controls the lock is an implementation choice.

Required Interface

interface IERC6982 {
    event DefaultLocked(bool locked);
    event Locked(uint256 tokenId, bool locked);

    function defaultLocked() external view returns (bool);
    function locked(uint256 tokenId) external view returns (bool);
}

The contract emits DefaultLocked(true) once at construction (or at init for proxies) so off-chain indexers can pre-compute "all unminted tokens are locked". Per-token Locked(tokenId, false) events flip individual entries.

Neo Equivalent: NEP-11 + Lock-State Storage

The Neo port adds a per-token lock-state storage prefix and a contract- level default-lock flag, plus a Transfer override that enforces the lock predicate. Storage layout:

• Prefix_DefaultLock (single byte) — collection-wide default.
• Prefix_Lock + tokenId — per-token override (presence = override applies; value = locked/unlocked bit).

public static bool Locked(ByteString tokenId)
{
    var override_ = Storage.Get(Storage.CurrentContext, LockKey(tokenId));
    return override_ is null
        ? DefaultLocked()
        : ((BigInteger)override_) == 1;
}

ERC-6982 (Ethereum)	Neo Equivalent	Notes
defaultLocked() view	DefaultLocked() view returning the single-byte storage value	Set once at deploy
locked(tokenId) view	Locked(tokenId) view honouring per-token override + default	Direct port
DefaultLocked(bool) event	OnDefaultLocked(bool) notification, fired once at deploy
Locked(tokenId, bool) event	OnLocked(tokenId, bool) notification per flip
Transfer-blocking enforcement	Transfer override checks Locked(tokenId) and reverts if locked	NEP-11 base hook

Lock-Controller Pattern

ERC-6982 doesn't standardise the controller; common patterns:

• Owner-controlled — token holder can lock/unlock their own NFT.
• Issuer-controlled — collection issuer locks/unlocks (escrow, KYC freeze).
• External-contract-controlled — a staking contract calls Lock(tokenId) when receiving deposits; Unlock(tokenId) on withdrawal.
• Multi-controller — multiple addresses approved to flip locks (e.g. lending protocol + insurance contract).

The contract author picks the model and exposes it via a SetLock(tokenId, bool) method gated on whichever witness check is appropriate. ERC-6982's interface only covers the read path; the write path is application-specific.

Composition

• ERC-5192 — minimal soulbound. Locked = soulbound; ERC-6982 is a strict superset that allows unlocking.
• ERC-5484 — consensual soulbound (with BurnAuth). Use 6982 for collections where holders should be able to opt back out of soulbinding.
• ERC-6147 — NFT guard delegate. Heavier than 6982; use when third-party guard authorisation is needed.
• ERC-4907 — rental NFT. Locks tend to apply during active rentals — Locked returns true iff the user role is set and not expired.

Migration Notes

For Solidity collections using ERC-6982:

• Direct port: per-token lock storage + override predicate; trivial in NEP-11 base.
• Combined with rental (ERC-4907): make Locked() resolve true whenever the user role is active.
• Combined with staking external contract: expose LockBy(tokenId, controller) so the staking contract can claim a lock without becoming the NFT owner; release on UnlockBy(tokenId, controller).

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

contract ERC6982 {
    bool public defaultLocked;
    mapping(uint256 => bool) internal _locked;          // override flag
    mapping(uint256 => bool) internal _hasOverride;     // presence flag

    event DefaultLocked(bool locked);
    event Locked(uint256 tokenId, bool locked);

    constructor(bool _defaultLocked) {
        defaultLocked = _defaultLocked;
        emit DefaultLocked(_defaultLocked);
    }

    function locked(uint256 tokenId) public view returns (bool) {
        return _hasOverride[tokenId] ? _locked[tokenId] : defaultLocked;
    }

    function _setLocked(uint256 tokenId, bool isLocked) internal {
        _hasOverride[tokenId] = true;
        _locked[tokenId]      = isLocked;
        emit Locked(tokenId, isLocked);
    }

    // Transfer override skipped for brevity — gates on `locked(tokenId)`.
}

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("LockableNFT")]
[ContractPermission("*", "*")]
[SupportedStandards(NepStandard.Nep11)]
public class LockableNFT : Nep11Token<TokenState>
{
    public override string Symbol => "LCKD";

    private const byte Prefix_DefaultLock = 0x60;
    private const byte Prefix_Lock        = 0x61;
    private const byte Prefix_Admin       = 0xff;

    [DisplayName("DefaultLocked")]
    public static event Action<bool> OnDefaultLocked;
    [DisplayName("Locked")]
    public static event Action<ByteString, bool> OnLocked;

    [DisplayName("_deploy")]
    public static void Deploy(object data, bool update)
    {
        if (update) return;
        var args = (object[])data;
        Storage.Put(Storage.CurrentContext, new byte[] { Prefix_Admin },       (UInt160)args[0]);
        Storage.Put(Storage.CurrentContext, new byte[] { Prefix_DefaultLock }, (bool)args[1] ? 1 : 0);
        OnDefaultLocked((bool)args[1]);
    }

    public static bool DefaultLocked()
        => (BigInteger)(Storage.Get(Storage.CurrentContext, new byte[] { Prefix_DefaultLock }) ?? ByteString.Empty) == 1;

    public static bool Locked(ByteString tokenId)
    {
        var override_ = Storage.Get(Storage.CurrentContext, LockKey(tokenId));
        return override_ is null
            ? DefaultLocked()
            : (BigInteger)override_ == 1;
    }

    public static void SetLock(ByteString tokenId, bool isLocked)
    {
        // Owner-controlled in this example. Substitute the witness check
        // for the desired controller pattern.
        if (!Runtime.CheckWitness(OwnerOf(tokenId))) throw new Exception("NEP11:NoAuth");
        Storage.Put(Storage.CurrentContext, LockKey(tokenId), isLocked ? 1 : 0);
        OnLocked(tokenId, isLocked);
    }

    // Block transfers when the token is locked. The base Nep11Token<T> doesn't
    // expose a virtual hook, so we redefine Transfer with `public new static`.
    public new static bool Transfer(UInt160 to, ByteString tokenId, object data = null)
    {
        if (Locked(tokenId)) throw new Exception("NEP11:Locked");
        return Nep11Token<TokenState>.Transfer(to, tokenId, data);
    }

    private static byte[] LockKey(ByteString tokenId)
        => new byte[] { Prefix_Lock }.Concat(tokenId);
}

When To Use Default-Locked True

For collections that mint into escrow / staking by default and only unlock on redemption (e.g. game items earned in-game and only tradeable after withdrawal), set defaultLocked = true at deploy. Per-token unlock flips happen on the redemption path.

For collections that are normally tradeable but support per-token freezing for compliance / fraud-response, set defaultLocked = false and use SetLock(tokenId, true) on the rare freeze.