The Deed track

The Deed track stands on its own. No contract outside it reads DeedNFT, and the only piece it shares with the rest of the protocol is the optional TokenRegistry lookup for payment tokens (token-registry.md). In the app's language the Clear Deed is, on the chain, a T-Deed (glossary). No service mints T-Deeds yet.

Deployed addresses are in the root README.md (Deployed addresses). Each contract's functions, roles and events are in smart-contracts.md.

How the contracts connect

DeedNFT is the hub; everything else either checks it or writes to it through a role.

• Minting asks the validator and the registry. DeedNFT.mintAsset requires ValidatorRegistry.isValidatorActive, then asks the chosen Validator for supportsAssetType, defaultOperatingAgreement and, if a FundManager is set, getServiceFee.
• The registry hands out the validator role. ValidatorRegistry.updateValidatorStatus and removeValidator call DeedNFT.addValidator / removeValidator so that the active validators hold VALIDATOR_ROLE there and inactive ones do not. They also call FundManager.updateValidatorRoles, which gives each active validator FEE_MANAGER_ROLE on the FundManager.
• Validation is written back by the validator. Validator.validateDeed reads the deed's traits with getTraitValue and records the result with DeedNFT.updateValidationStatus.
• Fees route through the FundManager. mintAsset calls FundManager.processPayment, which only accepts calls from a DeedNFT on its compatible list.
• Metadata follows the traits. DeedNFT.tokenURI asks MetadataRenderer.tokenURI first, and every trait write calls MetadataRenderer.syncTraitUpdate. setMetadataRenderer gives the renderer VALIDATOR_ROLE on DeedNFT so it can write the customMetadata trait back.
• The extensions read the deed and act for its owner. Subdivide checks DeedNFT.ownerOf, getValidationStatus and getTraitValue. Fractionalize moves the deed into its own custody, and FractionTokenFactory clones the share token for it.

The asset lifecycle

flowchart LR
  M["Minter"] -->|"mintAsset"| D["T-Deed<br/>isValidated = false"]
  V["Validator.validateDeed"] -->|"updateValidationStatus"| D
  D -->|"createSubdivision, mintUnit<br/>(Land or Estate only)"| S["Subdivide<br/>ERC-1155 units"]
  D -->|"createFraction"| F["Fractionalize<br/>holds the deed"]
  F -->|"mintShares"| T["FractionToken<br/>ERC-20 shares"]
  F -->|"unlockAsset"| O["Holder of every share"]

1. Mint

Only a MINTER_ROLE holder can mint, and it names the owner. mintAsset(owner, assetType, uri, definition, configuration, validatorAddress, token, salt):

• 1.
  The validator is validatorAddress, or the DeedNFT's default validator if that is zero. It must be active in the registry, implement IValidator, support the asset type and have a default operating agreement.
• 2.
  If a FundManager is set, the caller — not the owner — pays the validator's service fee in token through processPayment. If none is set, token must be the zero address.
• 3.
  With a non-zero salt the id is generateUniqueTokenId(owner, assetType, definition, salt), a hash reduced to nine digits. With salt zero it is the next sequential id, from 1.
• 4.
  The deed gets seven traits: assetType, isValidated (false), operatingAgreement (the validator's default agreement URI with the token id appended), definition, configuration, validator and beneficiary (the owner). DeedNFTMinted is emitted.

Asset types are the DeedNFT.AssetType enum: Land (0), Vehicle (1), Estate (2), CommercialEquipment (3). What a validator looks for in each is under land, vehicles, estates and commercial equipment.

2. Validate

A validator checks the deed's traits against the criteria for its asset type. Validator.validateDeed(tokenId) needs VALIDATOR_ROLE on that Validator, and reads the deed from the validator's primaryDeedNFT. It fails — emitting ValidationError and writing nothing — if the asset type is not supported, or if a required operating agreement or definition is missing or not recognised. Otherwise it checks that every required trait is present and non-empty, then calls DeedNFT.updateValidationStatus with the result.

• If an asset type has no criteria, validateDeed marks the deed valid. setupValidationCriteria loads the built-in presets; setValidationCriteria sets custom ones.
• validateDeed does not check which validator the deed names. Any active validator can validate any deed in its primary DeedNFT, and the validator trait becomes that validator.
• updateMetadata by the owner sets isValidated back to false and clears validator.
• isValidated, validator and beneficiary are reserved: setTrait and removeTrait refuse them for every caller, and only VALIDATOR_ROLE can set assetType. See Reserved traits.

The full rules are in validation-system.md.

3. Subdivide

A validated land or estate deed can be split into numbered units. The deed's owner calls Subdivide.createSubdivision and becomes the collection admin. The deed stays with its owner: subdivision does not take custody. Whoever owns the deed at the time mints units with mintUnit or batchMintUnits. Each unit is its own ERC-1155 id, (deedId << 128) | unitId, with a supply of one, and it inherits the deed's asset type, operating agreement, definition, configuration and validator. Units are validated one by one with Validator.validateSubdivisionUnit. See subdivision.md.

4. Fractionalize

createFraction moves the deed into Fractionalize and issues an ERC-20 against it. It does not check that the deed is validated. The caller becomes the collection admin and is the only one who can mint shares, up to totalShares. The deed comes back out through unlockAsset: before any shares are minted, to wherever the admin sends it; after, only for someone holding every minted share, whose shares are burned, which needs the fraction to be burnable. createFraction also accepts a subdivision unit, but that path always reverts; see smart-contracts.md. More in fractionalization.md.

5. Transfer and royalties

T-Deeds move like any ERC-721, but only an approved marketplace can move one for its owner. Royalty enforcement is on from initialize. With it on, approve and setApprovalForAll revert ("!mkt") for an operator that is not on the setApprovedMarketplace list, and so does a transfer sent by anyone other than the owner or an approved marketplace. Each transfer rewrites the beneficiary trait to the new owner. royaltyInfo names the deed's validator contract as the receiver, at that validator's royaltyFeePercentage — 5% by default, and never more.

Pausing DeedNFT stops minting, burning and updateMetadata, not transfers. An owner can burn a deed with burnAsset or burnBatchAssets.

asset-workflows.md lists the calls for each step, in order.

Roles

Every contract starts with its deployer holding all of its roles. Who holds them now is in Governance.

Networks

The Deed track is deployed on Base Sepolia only. deployments/base-sepolia/ records DeedNFT, Validator, ValidatorRegistry, FundManager, MetadataRenderer, Subdivide, Fractionalize and FractionTokenFactory. FractionTokens are clones made per fraction. ValidatorFactory has no deploy script and is not deployed. Nothing on Base mainnet or Ethereum Sepolia belongs to the Deed track.

How the contracts are deployed and wired, and what the scripts leave for an admin to do afterwards, is in smart-contracts.md and Operators.

Known limitations

• DeedNFT has no getAssetType. Subdivide calls it, so setting a unit's assetType trait reverts. See subdivision.md.
• A subdivision unit cannot be fractionalized. Fractionalize has no onERC1155Received, so receiving a unit reverts.
• The checkApprovals unlock path never passes. adminApprovals is never set.
• A non-burnable fraction cannot be unlocked once shares are minted. Unlocking burns the shares. See fractionalization.md.
• ValidatorFactory.createValidator reverts. Validator disables initializers in its constructor, so the factory cannot initialize the validator it deploys.
• No tests cover Subdivide, Fractionalize or ValidatorFactory. DeedNFT, Validator, ValidatorRegistry, FundManager and MetadataRenderer have tests in test/core/.