ERC-5114 — Soulbound Badge

Back to Token Standards

ERC-5114: Soulbound Badge (Bound to NFT)

ERC-5114 defines tokens that are bound to a parent NFT rather than to an account — a badge attached to your CryptoPunk, an achievement attached to your in-game character, a delegation marker attached to a governance NFT. The badge follows the parent NFT through transfers but cannot be moved independently.

Required Interface

function ownerOf(uint256 badgeId)
    external view returns (uint256 nftAddressAndId);    // packed: addr | tokenId
function collectionUri()                external view returns (string memory);
function badgeUri(uint256 badgeId)      external view returns (string memory);

Neo Equivalent: Direct Port

Neo C# port: each badge stores a reference to its parent (parent contract hash + tokenId). The badge's effective owner is whoever owns the parent NFT; resolved on each query.

Live on Neo TestNet

Both implementations are deployed on Neo N3 TestNet (network magic 894710606).

Implementation	Contract Hash	Deploy Tx
Solidity (neo-solc)	0x91e34b16c373f845024013c3bd585ac9739b741f	0x8cca8503…3a8c3a19
Neo C# (nccs)	0xd9d32f5f8d2d0cd5196cd94b49e3d11ac46d7039	0x7dd08b98…170ee73

Cross-implementation invocations match on claimDeployer, badgeCount, getOwner. Source pairs under docs/standards-mirror/deployments/erc-5114/.

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

interface IERC5114 {
    function ownerOf(uint256 badgeId) external view returns (uint256);
    function collectionUri() external view returns (string memory);
    function badgeUri(uint256 badgeId) external view returns (string memory);
}

contract Achievement is IERC5114 {
    struct Parent { address nft; uint256 tokenId; }
    mapping(uint256 => Parent) private _parent;
    mapping(uint256 => string) private _uri;
    string private _collectionUri;

    function attach(uint256 badgeId, address nft, uint256 tokenId, string calldata uri) external {
        require(_parent[badgeId].nft == address(0), "already attached");
        _parent[badgeId] = Parent(nft, tokenId);
        _uri[badgeId] = uri;
    }

    function ownerOf(uint256 badgeId) external view returns (uint256) {
        Parent memory p = _parent[badgeId];
        // Pack: high 160 bits = nft address, low 96 bits = tokenId (truncated).
        return (uint256(uint160(p.nft)) << 96) | (p.tokenId & ((1 << 96) - 1));
    }

    function collectionUri() external view returns (string memory) { return _collectionUri; }
    function badgeUri(uint256 badgeId) external view returns (string memory) {
        return _uri[badgeId];
    }
}

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("Achievement")]
[ContractPermission("*", "*")]
public class Achievement : SmartContract
{
    private const byte Prefix_ParentNft = 0x01;
    private const byte Prefix_ParentTok = 0x02;
    private const byte Prefix_Uri       = 0x03;

    [DisplayName("Attached")]
    public static event Action<ByteString, UInt160, ByteString> OnAttached;

    /// <summary>
    /// Returns (parentContract, parentTokenId) — the badge's owner is whoever
    /// owns that NFT, resolved on demand by calling parentContract.ownerOf(parentTokenId).
    /// </summary>
    public static (UInt160, ByteString) ParentOf(ByteString badgeId)
    {
        var nft = (UInt160)Storage.Get(Storage.CurrentContext,
                                       new byte[] { Prefix_ParentNft }.Concat(badgeId));
        var tok = Storage.Get(Storage.CurrentContext,
                              new byte[] { Prefix_ParentTok }.Concat(badgeId));
        if (nft == null) throw new Exception("badge not attached");
        return (nft, tok);
    }

    /// <summary>Resolves through the parent NFT to find the actual holder.</summary>
    public static UInt160 EffectiveOwnerOf(ByteString badgeId)
    {
        var (nft, tok) = ParentOf(badgeId);
        return (UInt160)Contract.Call(nft, "ownerOf", CallFlags.ReadOnly, new object[] { tok });
    }

    public static void Attach(ByteString badgeId, UInt160 parentNft, ByteString parentTokenId,
                              string uri)
    {
        if (!Runtime.CheckWitness(GetAdmin())) throw new Exception("admin only");
        if (Storage.Get(Storage.CurrentContext,
                        new byte[] { Prefix_ParentNft }.Concat(badgeId)) != null)
            throw new Exception("already attached");

        Storage.Put(Storage.CurrentContext,
                    new byte[] { Prefix_ParentNft }.Concat(badgeId), parentNft);
        Storage.Put(Storage.CurrentContext,
                    new byte[] { Prefix_ParentTok }.Concat(badgeId), parentTokenId);
        Storage.Put(Storage.CurrentContext,
                    new byte[] { Prefix_Uri }.Concat(badgeId), uri);
        OnAttached(badgeId, parentNft, parentTokenId);
    }

    public static string BadgeUri(ByteString badgeId)
        => (string)Storage.Get(Storage.CurrentContext,
                               new byte[] { Prefix_Uri }.Concat(badgeId));

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