Deed track contracts

Their interfaces are in contracts/core/interfaces/: IDeedNFT, IValidator, IValidatorRegistry, IFundManager, IMetadataRenderer, ISubdivide, IFractionalize, IFractionTokenFactory. DeedNFT does not declare that it implements IDeedNFT, and the two differ — see Subdivide.

Every contract's initialize grants all of its roles, or its ownership, to the deployer.

DeedNFT

The T-Deed: one ERC-721 token per real-world asset, described by traits. Imports Limit Break's ICreatorToken for the royalty-enforcement interface, and reports ERC-7496 (0xaf332f3e) in supportsInterface.

State: nexttokenId (from 1), the default validator, the validator registry, metadataRenderer, fundManager, the trait store (tokenId → key → bytes) and trait names, the approved-marketplace list and the royalty-enforcement flag. totalSupply is a running count of live tokens.

Royalty enforcement. While on, approve and setApprovalForAll revert with "!mkt" for an operator not on the marketplace list, and _beforeTokenTransfer reverts a transfer whose sender is neither the owner nor an approved marketplace. Every transfer also rewrites beneficiary.

Events: DeedNFTMinted, DeedNFTBurned, DeedValidated, TraitUpdated, MetadataRendererUpdated, ContractURIUpdated, MarketplaceApproved, RoyaltyEnforcementChanged, TransferValidatorUpdated.

Validator

Checks deeds and units against per-asset-type criteria, and sets what a deed costs to mint and pays in royalties. One Validator serves one primary DeedNFT plus a list of compatible contracts (which must include Subdivide for unit validation). It is both Ownable and AccessControl.

State: baseUri, defaultOperatingAgreementUri, primaryDeedNFT and compatibleDeedNFTs, supportedAssetTypes, validationCriteria per asset type (requiredTraits, additionalCriteria, requireOperatingAgreement, requireDefinition), named operating agreements, the payment-token whitelist and serviceFee per token, royaltyFeePercentage (default 500 bps) and royaltyReceiver, fundManager, tokenRegistry.

Recognising an operating agreement. validateDeed accepts an agreement that is registered exactly, contains baseUri, or contains any URI passed to registerOperatingAgreement. A new deed's agreement is the default URI with its token id appended, so it passes only if the default URI contains baseUri or has been registered. The public validateOperatingAgreement uses a different rule — registered exactly, or containing the default URI.

ADMIN_ROLE is declared and checked by FundManager.withdrawValidatorFees, but initialize grants it to no one.

Events: DeedValidated, ValidationError, ValidationCriteriaUpdated, OperatingAgreementRegistered, DeedNFTUpdated, PrimaryDeedNFTUpdated, CompatibleDeedNFTUpdated, RoyaltyWithdrawn.

ValidatorRegistry

The list of validators, and the switch that turns each one on. A validator is registered inactive; activating it is what lets DeedNFT mint against it and lets it write validation.

State: validators (isActive, supportedAssetTypes, name, description), assetTypeValidators (asset type → validator addresses), the address list, fundManager, deedNFT.

Every function that changes state is onlyOwner. REGISTRY_ADMIN_ROLE is granted to the deployer and checked by none of them.

Events: ValidatorRegistered (also emitted on rename, and on removal with an empty name), ValidatorStatusUpdated, ValidatorAssetTypesUpdated, DeedNFTUpdated.

FundManager

Takes the service fee at mint and keeps each validator's share until it is withdrawn.

State: compatibleDeedNFTs, validatorRegistry, the commission in basis points, feeReceiver, per-validator per-token balances, the list of validators it has given FEE_MANAGER_ROLE, a token list, tokenRegistry.

MINTER_ROLE is granted to the deployer and checked by nothing.

Events: ServiceFeeCollected, ValidatorFeesWithdrawn, CommissionPercentageUpdated, FeeReceiverUpdated, ValidatorRegistryUpdated, CompatibleDeedNFTUpdated.

MetadataRenderer

Builds the JSON DeedNFT.tokenURI returns. It combines the deed's traits with what it stores itself, keyed by token id for its one deedNFT. An unvalidated deed shows the invalidated image (defaultImageURIs[255]). The output format is in metadata-renderer.md.

State: default image and background colour per asset type; per token, the stored metadata (name, description, image, colours, animation URL, external link, gallery, documents, custom metadata), features, condition and legal information.

Events: MetadataUpdate, MetadataSynced.

Subdivide

Splits a validated Land or Estate deed into ERC-1155 units, each its own token with a supply of one. The unit's token id is (deedId << 128) | unitId. The deed stays with its owner.

State: subdivisions per deed (name, description, symbol, collectionUri, totalUnits, activeUnits, isActive, burnable, collectionAdmin, subdivisionValidator, per-unit metadata), unit traits, unit owners, deedNFT, validatorRegistry. defaultValidator is set to zero at initialize and has no setter, so a unit's validator is the subdivision's, or else the deed's.

The deed is not locked. Its owner can still transfer or burn it. Minting units follows the deed's current owner; the collection admin stays whoever created the subdivision until it is handed on.

DeedNFT has no getAssetType. IDeedNFT declares it and Subdivide calls it, so setUnitTrait or setUnitTraitFlexible on the assetType key reverts, as does getUnitAssetType for a unit with no assetType trait of its own.

No tests cover Subdivide.

Events: SubdivisionCreated, UnitMinted, UnitBurned, UnitValidated, UnitTraitUpdated, UnitMetadataUpdated, BurnableStatusChanged, SubdivisionValidatorUpdated, SubdivisionDeactivated, CollectionAdminTransferred, MarketplaceApproved, RoyaltyEnforcementChanged.

Fractionalize

Holds a deed and issues ERC-20 shares against it. Each fraction has an id from nextFractionId (from 1) and its own FractionToken.

State per fraction: name, description, symbol, collectionUri, totalShares, activeShares, maxSharesPerWallet (set to totalShares), requiredApprovalPercentage, isActive, burnable, the asset type and original token id, collectionAdmin, tokenAddress.

Who can unlock. With no shares minted, only the collection admin. With shares minted, the caller must hold every minted share (getVotingPower == activeShares); those shares are burned first. The checkApprovals route compares the caller's adminApprovals against requiredApprovalPercentage, but no function sets approvals, so it never passes.

What blocks an unlock or a lock:

• Burning shares needs burnable. A non-burnable fraction cannot be unlocked once any share is minted.
• Shares burned with FractionToken.burn directly do not reduce activeShares, after which no one can hold "every minted share". Burn through burnShares.
• createFraction moves a deed with transferFrom, sent by Fractionalize. While DeedNFT enforces royalties, Fractionalize must be on its setApprovedMarketplace list for both the owner's approve and the transfer to succeed.
• A subdivision unit is moved with safeTransferFrom, which requires the receiver to implement onERC1155Received. Fractionalize does not, so fractionalizing a unit reverts.

No tests cover Fractionalize, FractionToken or FractionTokenFactory.

Events: FractionCreated, AssetLocked, SharesMinted, SharesBurned, AssetUnlocked.

FractionToken

The ERC-20 share token for one fraction. Records fractionalizeContract and fractionId.

Each token is an EIP-1167 clone initialized by the factory, so the factory holds its admin roles — and the factory has no function that uses them. The admin setters, pause and upgrade cannot be reached. A clone has no ERC-1967 implementation slot, so UUPS's onlyProxy check would refuse an upgrade anyway.

Events: MaxSharesPerWalletUpdated, BurnableStatusUpdated.

FractionTokenFactory

Clones the FractionToken implementation for each fraction. initialize deploys the implementation with new FractionToken().

Events: FractionTokenCreated, ImplementationUpdated.

ValidatorFactory

Meant to deploy a configured Validator and register it in one call. It has no deploy script, is not in deployments/, and has no tests.

createValidator(name, description, supportedAssetTypes, royaltyFeePercentage, serviceFee, baseUri, operatingAgreementUri) is open to anyone. It deploys new Validator() and calls initialize on it directly, but Validator's constructor calls _disableInitializers(), so that call reverts. Even past that, ValidatorRegistry.registerValidator is onlyOwner, so the factory would have to own the registry. Its owner-only setters are addDefaultWhitelistedToken, removeDefaultWhitelistedToken, updateValidatorRegistry and updateFundManager. Events: ValidatorCreated, TokenWhitelisted, TokenRemovedFromWhitelist.

Deployment and wiring

deploy/deploy_all.ts deploys and wires ValidatorRegistry, MetadataRenderer, Validator, DeedNFT, FundManager and Subdivide; deploy/06_deploy_Fractionalize.ts adds FractionTokenFactory and Fractionalize. All are UUPS proxies. The numbered scripts 00–04 call roles and functions the current contracts do not have — OPERATOR_ROLE, ADMIN_ROLE on DeedNFT and MetadataRenderer, setAssetTypeSupported, FundManager.setDeedNFT, and initializer arguments that no longer match — so deploy_all.ts is the one that runs against them. 05 matches the current Subdivide.

What deploy_all.ts wires:

• 1.
  ValidatorRegistry.setDeedNFT, Validator.setDeedNFT, MetadataRenderer.setDeedNFT and DeedNFT.setMetadataRenderer, plus the renderer's default images.
• 2.
  ValidatorRegistry.setFundManager, then registerValidator and updateValidatorStatus(true) for the default validator — which grants it VALIDATOR_ROLE on DeedNFT and FEE_MANAGER_ROLE on the FundManager.
• 3.
  Validator.setAssetTypeSupport for all four types (no criteria) and Validator.setFundManager.
• 4.
  Subdivide ADMIN_ROLE to the deployer and VALIDATOR_ROLE to the validator.

What it leaves for an admin:

• DeedNFT.setFundManager — until then minting charges no fee. Once it is set, FundManager.addCompatibleDeedNFT(DeedNFT) must be too, or every mint reverts in processPayment.
• Validator.setupValidationCriteria or setValidationCriteria — until then every supported deed validates.
• Validator.registerOperatingAgreement for the default agreement.
• Validator.addCompatibleDeedNFT(Subdivide) — until then validateSubdivisionUnit reverts.
• DeedNFT.setApprovedMarketplace(Fractionalize, true) — until then createFraction reverts while royalties are enforced.

deployments/ does not record whether these were done on Base Sepolia. The Validator and FundManager ABIs saved in deployments/base-sepolia/ predate setTokenRegistry. Upgrades use deploy/upgrade/; the steps are in Operators.