Real Estate Tokenization on ERC721: Architecture and Patterns

RealT, Lofty, and Propy each ship variants of the same architecture. The property gets its own deed NFT. The deed NFT references a per property ERC20 share token. The shares are sold to investors after KYC. The on chain shares are backed by an off chain legal entity — usually a Special Purpose Vehicle (SPV) or LLC formed specifically to own the property.

The interesting engineering is in the seams. How does the deed contract know that the off chain entity really holds title. How do the share transfers stay compliant. How does rent flow from the property to thousands of small holders without blowing the gas budget. This post walks through the contract patterns each of those questions resolves into.

If you have not read the ERC standards overview, the two token model below will feel arbitrary. With the standards in mind, it is the only shape that maps cleanly onto how real estate actually transfers.

// Deed NFT — one tokenId per property, points to the off chain legal pointer
contract PropertyDeed is ERC721, AccessControl {
    bytes32 public constant CUSTODIAN_ROLE = keccak256("CUSTODIAN_ROLE");

    struct Property {
        bytes32 legalEntityHash;   // hash of the off chain SPV / LLC documents
        address fractionalToken;   // ERC20 share token for this property
        uint128 appraisedValueUsd; // last appraisal, off chain attested
        uint64 lastAppraisedAt;    // unix timestamp
    }

    mapping(uint256 => Property) public property;

    constructor() ERC721("Property Deed", "DEED") {
        _grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
    }

    function registerProperty(
        uint256 tokenId,
        address custodian,
        Property calldata p
    ) external onlyRole(DEFAULT_ADMIN_ROLE) {
        property[tokenId] = p;
        _safeMint(custodian, tokenId);
    }

    // Only the custodian role can ever transfer the deed
    function _beforeTokenTransfer(
        address from,
        address to,
        uint256 tokenId,
        uint256 batchSize
    ) internal override {
        super._beforeTokenTransfer(from, to, tokenId, batchSize);
        if (from == address(0)) return; // mint always allowed
        require(hasRole(CUSTODIAN_ROLE, to), "Deed: receiver not a custodian");
    }
}

The Property struct compresses the per property data: a hash of the legal entity documents, the address of the share token, the last appraised value, and the appraisal timestamp. Storing the legal hash on chain gives auditors and regulators a tamper proof reference to the off chain paperwork without putting the documents themselves on chain.

The transfer hook restricts who can hold the deed. Only addresses with the CUSTODIAN_ROLE can receive a deed NFT. This prevents a deed from ending up in a random wallet — which would create a mismatch between the on chain pointer and the off chain title holder. When custodians need to change (sale of the property, change of trustee), the deed transfers from one custodian wallet to another.

// Per property ERC20 share token — KYC gated transfers
contract PropertyShares is ERC20, AccessControl {
    bytes32 public constant KYC_ROLE = keccak256("KYC_ROLE");
    bytes32 public constant ISSUER_ROLE = keccak256("ISSUER_ROLE");

    uint256 public immutable deedTokenId;
    address public immutable deedContract;

    mapping(address => bool) public kycPassed;

    constructor(
        string memory name_,
        string memory symbol_,
        uint256 initialSupply,
        uint256 _deedTokenId,
        address _deedContract,
        address issuer
    ) ERC20(name_, symbol_) {
        deedTokenId = _deedTokenId;
        deedContract = _deedContract;
        _grantRole(DEFAULT_ADMIN_ROLE, issuer);
        _grantRole(ISSUER_ROLE, issuer);
        _mint(issuer, initialSupply);
    }

    function setKyc(address holder, bool passed) external onlyRole(KYC_ROLE) {
        kycPassed[holder] = passed;
    }

    function _beforeTokenTransfer(address from, address to, uint256)
        internal
        override
    {
        if (from != address(0)) require(kycPassed[from], "Shares: sender not KYC");
        if (to != address(0))   require(kycPassed[to], "Shares: receiver not KYC");
    }
}

Each share token instance is deployed once per property. Total supply is fixed at issuance — typically 100,000 or 1,000,000 shares per property — and represents the economic claim on net rent plus resale proceeds.

The KYC mapping is the heart of the compliance model. A KYC oracle wallet (operated by the issuer or a compliance vendor) calls setKyc(holder, true) after the holder passes off chain identity verification. The transfer hook reverts any transfer where either party has not passed KYC. The hook runs on direct transfers and on transfers initiated by a DEX router, so shares cannot leak to unverified wallets through a swap.

Production deployments combine this with a transfer agent role that can force transfer shares to resolve disputes or enforce court orders. The transfer agent is usually a regulated entity in the jurisdiction where the property sits.

When rent is collected off chain (or paid in stablecoin on chain), the issuer deposits the rent into the distributor contract. The distributor takes a snapshot of the share token, records the round, and waits. Each holder claims their share by calling the distributor — once per round.

// Pull payment dividend distributor — gas safe even with thousands of holders
contract RentDistributor {
    IERC20Snapshot public immutable shares;
    IERC20 public immutable stablecoin;

    struct Round {
        uint256 snapshotId;
        uint256 totalDeposited;
        uint256 totalSupplyAtSnapshot;
        mapping(address => bool) claimed;
    }

    mapping(uint256 => Round) public rounds;
    uint256 public currentRound;

    function depositRent(uint256 amount) external {
        stablecoin.transferFrom(msg.sender, address(this), amount);
        currentRound += 1;
        Round storage r = rounds[currentRound];
        r.snapshotId = shares.snapshot();
        r.totalDeposited = amount;
        r.totalSupplyAtSnapshot = shares.totalSupplyAt(r.snapshotId);
        emit RentDeposited(currentRound, amount);
    }

    function claim(uint256 roundId) external {
        Round storage r = rounds[roundId];
        require(!r.claimed[msg.sender], "already claimed");
        uint256 bal = shares.balanceOfAt(msg.sender, r.snapshotId);
        require(bal > 0, "no shares at snapshot");

        uint256 owed = (r.totalDeposited * bal) / r.totalSupplyAtSnapshot;
        r.claimed[msg.sender] = true;
        stablecoin.transfer(msg.sender, owed);
        emit RentClaimed(roundId, msg.sender, owed);
    }
}

The pattern has three properties that matter. First, the deposit is constant cost regardless of holder count — the issuer never loops. Second, holders who never claim simply leave their pro rata share in the distributor; the issuer can sweep unclaimed balances after a long timeout. Third, the snapshot at deposit time fixes who gets paid, so trading shares mid round does not create a dispute.

RealT runs the simplest model — every property gets its own ERC20 with a transfer whitelist, deployed on a cheap chain to keep dividend gas low. Lofty pushes most of the policy off chain through a regulated transfer agent. Propy focuses on the deed NFT and treats fractionalization as optional. None of them has fully on chain title transfer because no jurisdiction recognizes that yet.

Decide whether the deed NFT is on the same chain as the share token. Some platforms keep the deed on Ethereum (for legitimacy in legal disputes) and the shares on a cheap L2 (for affordable dividend payouts). The two contracts reference each other through bridge attestations, which adds complexity but separates the audit surfaces.

Pick a fixed total share supply per property up front. Variable supply complicates capital structure and confuses retail holders. The standard pattern is to mint the full supply at issuance, hold the unsold portion in an issuer treasury, and release through primary sales.

Treat the KYC oracle as the most attacked surface. A compromised KYC wallet can mark adversary addresses as passed and exfiltrate shares. The oracle should be a multisig with rate limits, not a hot wallet. Most production platforms move the KYC role to a regulated entity over time.

We help teams ship tokenized real world asset systems end to end — the deed and share contracts, the KYC oracle, the dividend distributor, the integration with the off chain custodian, and the operational playbook for the first 100 properties. The adjacent NFT ticketing deep dive covers the other major ERC721 use case where transfer hooks do most of the operational work.