NFT Layer (ERC-721)

Overview

The NFT layer represents unique, non-fungible assets — a single land parcel deed, a single property title, a single mining license, a single certified warehouse receipt. It mirrors the ERC-20 layer’s architecture (UUPS proxies, role-based access, pluggable identity verifier) but issues ERC721Upgradeable tokens instead of fungible balances.

packages/contracts-evm/contracts/
├── base/
│   └── AnkaraNFTBase.sol         ← Abstract ERC-721 UUPS base
├── interfaces/
│   └── IAnkaraNFT.sol
├── templates/
│   ├── FarmlandNFT.sol
│   ├── RealEstateNFT.sol
│   ├── MiningRightsNFT.sol
│   └── CommodityVaultNFT.sol
└── factory/
    └── NFTFactory.sol

AnkaraNFTBase

Abstract base contract inherited by all four NFT templates. Provides:

ERC721Upgradeable — standard non-fungible token
ERC721PausableUpgradeable — halt transfers
ERC721BurnableUpgradeable — token burning
AccessControlUpgradeable — role-based permissions
UUPSUpgradeable — upgrade authorization

Roles

bytes32 public constant MINTER_ROLE   = keccak256("MINTER_ROLE");
bytes32 public constant PAUSER_ROLE   = keccak256("PAUSER_ROLE");
bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");
bytes32 public constant MANAGER_ROLE  = keccak256("MANAGER_ROLE");

All roles are granted to admin_ at initialization, same as the ERC-20 base.

State

bytes32 private _assetId;
string  private _countryCode;
AssetStatus private _status;               // DRAFT(0) → ACTIVE(1) → ...
IIdentityVerifier private _identityVerifier;
address public linkedERC20;                // optional link to an ERC-20 investment token
uint256 private _nextTokenId;              // starts at 1
uint256[49] private __gap;

linkToERC20() (MANAGER_ROLE) lets an NFT deed reference a companion fungible token — for example, a RealEstateNFT deed backing a RealEstateToken that represents fractional ownership of the same property.

Minting

Templates call the internal _mintNext(to) helper, which auto-increments the token ID starting at 1 and runs the identity-verifier check before minting:

function _mintNext(address to) internal returns (uint256 tokenId) {
    tokenId = _nextTokenId++;
    _checkVerified(to);
    _safeMint(to, tokenId);
}

Transfer Hook

Every mint, burn, and transfer passes through _update(), exactly like the ERC-20 base’s _update() — the identity verifier is checked for both from and to when set (skipped on mint for from, skipped on burn for to):

function _update(address to, uint256 tokenId, address auth)
    internal virtual override(ERC721Upgradeable, ERC721PausableUpgradeable)
    returns (address)
{
    address from = _ownerOf(tokenId);
    if (from != address(0) && address(_identityVerifier) != address(0)) {
        _checkVerified(from);
    }
    if (to != address(0) && address(_identityVerifier) != address(0)) {
        _checkVerified(to);
    }
    return super._update(to, tokenId, auth);
}

Templates

Template	Purpose
`FarmlandNFT`	Unique land parcel deed
`RealEstateNFT`	Unique property title
`MiningRightsNFT`	Unique mining license
`CommodityVaultNFT`	Certified warehouse receipt

Each template extends AnkaraNFTBase with its own metadata struct (e.g. RealEstateNFTMetadata has propertyId, propertyType, locationAddress, titleDocumentHash, valuationUSD, rentalYieldBps, etc.) and a mint(address to, ...metadata) function restricted to MINTER_ROLE.

NFTFactory

Deploys all four NFT templates via ERC1967Proxy, following the exact same pattern as TokenFactory:

enum NFTTemplate { FARMLAND, REAL_ESTATE, MINING_RIGHTS, COMMODITY_VAULT }
mapping(NFTTemplate => address) public implementations;

Owner registers an implementation address per template via registerTemplate()
Developer calls deployFarmlandNFT() / deployRealEstateNFT() / deployMiningRightsNFT() / deployCommodityVaultNFT()
Factory deploys an ERC1967Proxy pointing at the registered implementation
The developer’s admin_ address receives full role-based control of the new NFT contract
An optional native-token deployment fee is collected (0 during testnet)

Deploy event:

event NFTDeployed(
    NFTTemplate indexed template,
    address indexed nftAddress,
    address indexed deployer,
    bytes32 assetId,
    string  countryCode,
    uint256 timestamp
);

Registry views: totalDeployedNFTs(), getDeployerNFTs(address deployer).

SDK Integration

TokenFactory.deployFarmlandNFT() / deployRealEstateNFT() / deployMiningRightsNFT() / deployCommodityVaultNFT() wrap the factory calls, plus getDeployedNFTs() and totalDeployedNFTs() for the registry views. See the CLI’s ankara deploy-nft command for an interactive example.

Running the NFT Tests Locally

cd packages/contracts-evm
npm run test -- --grep "NFT"

Getting Started

Stellar

CLI

Asset Templates

Smart Contracts

MCP Server

Overview

AnkaraNFTBase

Roles

State

Minting

Transfer Hook

Templates

NFTFactory

SDK Integration

Running the NFT Tests Locally

​Overview

​AnkaraNFTBase

​Roles

​State

​Minting

​Transfer Hook

​Templates

​NFTFactory

​SDK Integration

​Running the NFT Tests Locally

Overview

AnkaraNFTBase

Roles

State

Minting

Transfer Hook

Templates

NFTFactory

SDK Integration

Running the NFT Tests Locally