> For the complete documentation index, see [llms.txt](https://docs.doma.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.doma.xyz/api-reference/doma-smart-contracts-api/evm-proxy-doma-record-api.md). # (EVM) Proxy Doma Record API User-facing facet for the Proxy DOMA record contract on tokenization chains. *This facet handles user interactions including tokenization requests, ownership claims, cross-chain bridging, and domain record management. It validates vouchers, manages fees, and integrates with EIP-712 for signature verification. Supports both ownership tokens and capability tokens with appropriate access controls.* {% file src="/files/8LNnQE2vkOb1LFyVt982" %} ## Structs #### TokenizationVoucher Tokenization voucher, obtained from a Registrar. **Parameters** | Name | Type | Description | | ------------ | ------------------------------ | ---------------------------------------------- | | names | struct IDomaRecord.NameInfo\[] | List of names to tokenize. | | nonce | uint256 | Unique nonce to prevent replay attacks. | | expiresAt | uint256 | Expiration timestamp (UNIX seconds) | | ownerAddress | address | Address to receive the minted ownership token. | ```solidity struct TokenizationVoucher { struct IDomaRecord.NameInfo[] names; uint256 nonce; uint256 expiresAt; address ownerAddress; } ``` #### ProofOfContactsVoucher Proof of Contacts voucher, obtained from a Registrar or Doma-provided storage. **Parameters** | Name | Type | Description | | ---------------- | -------------------------------------- | --------------------------------------- | | registrantHandle | uint256 | The registrant's handle identifier. | | proofSource | enum IDomaRecord.ProofOfContactsSource | Source of the proof (REGISTRAR or DOMA) | | nonce | uint256 | Unique nonce to prevent replay attacks. | | expiresAt | uint256 | Expiration timestamp (UNIX seconds) | ```solidity struct ProofOfContactsVoucher { uint256 registrantHandle; enum IDomaRecord.ProofOfContactsSource proofSource; uint256 nonce; uint256 expiresAt; } ``` #### HostDNSInput A host with its associated DNS record sets, used for batch DNS operations. **Parameters**
NameTypeDescription
hoststringThe hostname relative to the token (eg. "www" or "" for apex). Must be lowercase.
recordSetsstruct IDomaRecord.DNSRecordSet[]Array of DNS record sets for this host.
```solidity struct HostDNSInput { string host; struct IDomaRecord.DNSRecordSet[] recordSets; } ``` #### DNSRecordSet A single DNS record set containing a record type, TTL and values. **Parameters**
NameTypeDescription
recordTypestringDNS record type (eg "A", "AAAA", "CNAME").
ttluint32Time to live in seconds.
recordsstring[]Array of record values. Empty array deletes the RRSet.
```solidity struct DNSRecordSet { string recordType; uint32 ttl; string[] records; } ``` ## Errors #### InsufficientCapabilities ```solidity error InsufficientCapabilities(uint256 tokenId, uint256 requiredCapability) ``` Thrown when a token lacks the required capabilities for an operation. #### Parameters | Name | Type | Description | | ------------------ | ------- | ---------------------------------------- | | tokenId | uint256 | The ID of the token being checked | | requiredCapability | uint256 | The capability bitmask that was required | #### NameAlreadyTokenized ```solidity error NameAlreadyTokenized(string sld, string tld) ``` Thrown when attempting to tokenize a name that is already tokenized. **Parameters** | Name | Type | Description | | ---- | ------ | ----------------------------------- | | sld | string | The second-level domain of the name | | tld | string | The top-level domain of the name | #### InvalidRegistrar ```solidity error InvalidRegistrar(uint256 ianaId, uint256 expectedIanaId) ``` Thrown when a registrar ID doesn't match the expected registrar for an operation. **Parameters** | Name | Type | Description | | -------------- | ------- | ------------------------------ | | ianaId | uint256 | The provided registrar IANA ID | | expectedIanaId | uint256 | The expected registrar IANA ID | #### UnsupportedTargetChain ```solidity error UnsupportedTargetChain(string chainId) ``` Thrown when attempting to bridge to an unsupported target chain. **Parameters** | Name | Type | Description | | ------- | ------ | ----------------------------------------- | | chainId | string | The unsupported chain ID in CAIP-2 format | #### TransferLocked ```solidity error TransferLocked(uint256 tokenId) ``` Thrown when attempting to transfer a token that is locked for transfers. **Parameters** | Name | Type | Description | | ------- | ------- | -------------------------- | | tokenId | uint256 | The ID of the locked token | #### NameTokenHasExpired ```solidity error NameTokenHasExpired(uint256 tokenId, uint256 expiresAt) ``` Thrown when attempting to operate on an expired name token. **Parameters** | Name | Type | Description | | --------- | ------- | ------------------------------------- | | tokenId | uint256 | The ID of the expired token | | expiresAt | uint256 | The expiration timestamp of the token | #### InvalidSigner ```solidity error InvalidSigner(address signer) ``` Thrown when a voucher signature is invalid or from an unauthorized signer. **Parameters** | Name | Type | Description | | ------ | ------- | ------------------------------------------------- | | signer | address | The address that was recovered from the signature | #### VoucherExpired ```solidity error VoucherExpired(uint256 expiresAt, uint256 currentTime) ``` Thrown when a voucher has expired and cannot be used. **Parameters** | Name | Type | Description | | ----------- | ------- | --------------------------------------- | | expiresAt | uint256 | The expiration timestamp of the voucher | | currentTime | uint256 | The current block timestamp | #### PriceFeedStalePrice ```solidity error PriceFeedStalePrice(uint80 roundId, uint256 updatedAt) ``` Thrown when the price feed data is stale and cannot be trusted. **Parameters** | Name | Type | Description | | --------- | ------- | --------------------------------------------- | | roundId | uint80 | The round ID from the price feed | | updatedAt | uint256 | The timestamp when the price was last updated | #### InvalidPrice ```solidity error InvalidPrice(int256 price) ``` Thrown when the price feed returns an invalid price value. **Parameters** | Name | Type | Description | | ----- | ------ | -------------------------------- | | price | int256 | The invalid price value returned | #### TransferFailed ```solidity error TransferFailed() ``` Thrown when a native currency transfer fails. #### InvalidFee ```solidity error InvalidFee(uint256 expectedFee, uint256 providedFee) ``` Thrown when the provided fee doesn't match the expected fee for an operation. **Parameters** | Name | Type | Description | | ----------- | ------- | -------------------------------- | | expectedFee | uint256 | The expected fee amount in wei | | providedFee | uint256 | The fee amount actually provided | #### FeeNotRequired ```solidity error FeeNotRequired(bytes32 operation, uint256 nameCount) ``` Thrown when a fee is provided for an operation that doesn't require payment. **Parameters** | Name | Type | Description | | --------- | ------- | ----------------------------------- | | operation | bytes32 | The operation identifier | | nameCount | uint256 | The number of names being processed | #### NonceAlreadyUsed ```solidity error NonceAlreadyUsed(uint256 nonce) ``` Thrown when attempting to reuse a nonce that has already been consumed. **Parameters** | Name | Type | Description | | ----- | ------- | ------------------------------- | | nonce | uint256 | The nonce that was already used | #### FeeCollected ```solidity event FeeCollected(uint256 feeWei, uint256 feeUsdCents, string correlationId) ``` Emitted when a fee is collected for an operation. **Parameters** | Name | Type | Description | | ------------- | ------- | --------------------------------------------- | | feeWei | uint256 | The fee amount collected in wei | | feeUsdCents | uint256 | The equivalent fee amount in USD cents | | correlationId | string | The correlation ID for tracking the operation | #### SubdomainHostInUse ```solidity error SubdomainHostInUse(string host) ``` Thrown when attempting to set DNS records on a host that has an operational subdomain token. #### Parameters | Name | Type | Description | | ---- | ------ | --------------------------------------------------------- | | host | string | The host lable that conflicts with an existing subdomain. | #### EmptyArray ```solidity error EmptyArray() ``` Thrown when an empty array is passed to a batch operation. ## Methods #### requestTokenization ```solidity function requestTokenization(struct ProxyDomaRecordUserFacet.TokenizationVoucher voucher, bytes signature) external payable ``` Request tokenization of domain names using a signed voucher from a registrar. *Validates the voucher signature, collects fees, and initiates cross-chain tokenization. The voucher must be signed by an authorized registrar and not expired. Names are validated for proper format and checked for existing tokenization on this chain.* **Parameters** | Name | Type | Description | | --------- | --------------------------------------------------- | ------------------------------------------------------------------- | | voucher | struct ProxyDomaRecordUserFacet.TokenizationVoucher | The tokenization voucher containing names and authorization details | | signature | bytes | The registrar's signature over the voucher data | #### claimOwnership ```solidity function claimOwnership(uint256 tokenId, struct ProxyDomaRecordUserFacet.ProofOfContactsVoucher proofOfContactsVoucher, bytes signature) external payable ``` Claim ownership of a domain name using proof of contacts voucher. *Allows token owners to establish claim over their domain by providing signed proof from either the registrar or DOMA system. Validates voucher signature, collects fees, and initiates cross-chain ownership claim process.* **Parameters** | Name | Type | Description | | ---------------------- | ------------------------------------------------------ | ------------------------------------------------------- | | tokenId | uint256 | The ID of the ownership token being claimed | | proofOfContactsVoucher | struct ProxyDomaRecordUserFacet.ProofOfContactsVoucher | The voucher containing proof of contact information | | signature | bytes | The signature over the voucher (from registrar or DOMA) | #### bridge ```solidity function bridge(uint256 tokenId, string targetChainId, string targetOwnerAddress) external payable ``` Bridge a domain token to another supported chain. *Burns the token on this chain and initiates minting on the target chain. Validates target chain support, transfer lock status, and token expiration. Collects fees and relays the bridge request to the DOMA chain.* **Parameters** | Name | Type | Description | | ------------------ | ------- | -------------------------------------------- | | tokenId | uint256 | The ID of the ownership token to bridge | | targetChainId | string | The CAIP-2 chain ID of the destination chain | | targetOwnerAddress | string | The owner address on the target chain | #### requestDetokenization ```solidity function requestDetokenization(uint256 tokenId) external ``` Request detokenization of a domain name by the owner. *Initiates the detokenization process on the DOMA chain, which will remove the domain from the protocol and return it to traditional DNS management. Only the token owner can request detokenization.* **Parameters** | Name | Type | Description | | ------- | ------- | ------------------------------------------- | | tokenId | uint256 | The ID of the ownership token to detokenize | #### setNameservers ```solidity function setNameservers(uint256 tokenId, string[] nameservers) external payable ``` Update nameservers for a domain. *Requires CAPABILITY\_REGISTRY\_RECORDS\_MANAGEMENT. Relays change to Doma Chain.* **Parameters** | Name | Type | Description | | ----------- | --------- | ----------------------------- | | tokenId | uint256 | The ownership token ID. | | nameservers | string\[] | List of nameserver hostnames. | #### setDSKeys ```solidity function setDSKeys(uint256 tokenId, struct IDomaRecord.DSKey[] dsKeys) external payable ``` Update DNSSEC DS keys for a domain. *Requires CAPABILITY\_REGISTRY\_RECORDS\_MANAGEMENT. Relays change to Doma Chain.* **Parameters** | Name | Type | Description | | ------- | --------------------------- | ------------------------ | | tokenId | uint256 | The ownership token ID. | | dsKeys | struct IDomaRecord.DSKey\[] | Array of DS key records. | #### setDNSRRSet ```solidity function setDNSRRSet(uint256 tokenId, string host, string recordType, uint32 ttl, string[] records) external payable ``` Set DNS resource record set for a domain. Works for ownership tokens, synthetic root tokens and synthetic subdomain tokens. For subdomain tokens, the host is relative to the subdomain (use empty string for apex). *Requires CAPABILITY\_DNS\_RECORDS\_MANAGEMENT. Relays change to Doma Chain.* **Parameters** | Name | Type | Description | | ---------- | --------- | ------------------------------------------------------ | | tokenId | uint256 | The ownership token ID. | | host | string | The hostname (e.g., "www" or "@" for apex). | | recordType | string | DNS record type (e.g., "A", "AAAA", "CNAME"). | | ttl | uint32 | Time-to-live in seconds. | | records | string\[] | Array of record values. Empty array deletes the RRSet. | #### setDNSRRSetBatch ```solidity function setDNSRRSetBatch(uint256 tokenId, HostDNSInput[] hostInputs) external payable ``` Sets multiple DNS record sets across multiple hosts in a single transaction. Works for ownership tokens, synthetic root tokens and synthetic subdomain tokens. For subdomain tokens, hosts are relative to the subdomain (use empty string for apex). Each host entry must have at least one record set. Empty records array within a record set deletes that RRSet. *Requires CAPABILITY\_DNS\_RECORDS\_MANAGEMENT. Relays change to Doma Chain.* **Parameters** | Name | Type | Description | | ---------- | --------- | ------------------------------------------------------ | | tokenId | uint256 | The ownership token ID. | | host | string | The hostname (e.g., "www" or "@" for apex). | | recordType | string | DNS record type (e.g., "A", "AAAA", "CNAME"). | | ttl | uint32 | Time-to-live in seconds. | | records | string\[] | Array of record values. Empty array deletes the RRSet. | #### feesUSDCents ```solidity function feesUSDCents(bytes32 operation) public view returns (uint256) ``` Get the fee in USD cents for a specific operation. **Parameters** | Name | Type | Description | | --------- | ------- | --------------------------------- | | operation | bytes32 | The operation identifier to query | **Return Values** | Name | Type | Description | | ---- | ------- | --------------------------- | | \[0] | uint256 | The fee amount in USD cents | #### isTargetChainSupported ```solidity function isTargetChainSupported(string targetChainId) public view returns (bool) ``` Check if a target chain is supported for bridging operations. **Parameters** | Name | Type | Description | | ------------- | ------ | ------------------------------------ | | targetChainId | string | The CAIP-2 chain identifier to check | **Return Values** | Name | Type | Description | | ---- | ---- | ------------------------------------- | | \[0] | bool | Whether the target chain is supported | #### getNativePrice ```solidity function getNativePrice(uint256 feeUSDCents) public view returns (uint256 nativeFee) ``` Convert a USD cent amount to the equivalent native token amount. *Uses Chainlink price feed to get current exchange rate. Validates price feed data.* **Parameters** | Name | Type | Description | | ----------- | ------- | --------------------------- | | feeUSDCents | uint256 | The fee amount in USD cents | **Return Values** | Name | Type | Description | | --------- | ------- | -------------------------------------- | | nativeFee | uint256 | The equivalent fee in native token wei | #### getBridgeFeeInNative ```solidity function getBridgeFeeInNative(string targetChainId) public view returns (uint256) ``` Get the bridge fee in native tokens for a target chain. Uses per-chain bridge config when present, otherwise falls back to the default BRIDGE\_OPERATION fee **Parameters** | Name | Type | Description | | ------------- | ------ | ----------------------------------- | | targetChainId | string | The CAIP-2 target chain identifier. | **Return Values** | Name | Type | Description | | ---- | ------- | ----------------------------------- | | \[0] | uint256 | The fee amount in native token wei. | #### getOperationFeeInNative ```solidity function getOperationFeeInNative(bytes32 operation) public view returns (uint256) ``` Get the fee in native tokens for a specific operation. *Combines USD cent fee lookup with current price conversion.* **Parameters** | Name | Type | Description | | --------- | ------- | --------------------------------- | | operation | bytes32 | The operation identifier to query | **Return Values** | Name | Type | Description | | ---- | ------- | -------------------------------------------------------------- | | \[0] | uint256 | The fee amount in native token wei (0 if operation has no fee) | #### convertToSynthetic ```solidity function convertToSynthetic(uint256 tokenId) external payable ``` Convert an ownership token to a synthetic ownership token. Burns the ownership token and initiates minting of a synthetic token on the same chain via Doma Chain. The synthetic token maintains the same tokenId, expiration and capabilities as the original. **Parameters** | Name | Type | Description | | ------- | ------- | ----------------------------------------- | | tokenId | uint256 | The ID of the ownership token to convert. | #### convertToOwnership ```solidity function convertToOwnership(uint256 tokenId) external payable ``` Convert a synthetic ownership token back to a regular ownership token. Burns the synthetic token and initiates minting of an ownership token on the same chain via Doma Chain Requires that the synthetic token has no active subdomains. **Parameters** | Name | Type | Description | | ------- | ------- | ----------------------------------------- | | tokenId | uint256 | The ID of the synthetic token to convert. | #### mintSyntheticSubdomain ```solidity function mintSyntheticSubdomain(uint256 parentTokenId, string host, uint256 capabilities, uint256 expiresAt, bool revocable, uint256 groupId, address receiver) external payable returns (uint256) ``` Mint a synthetic subdomain token under a synthetic root token. The subdomain token grants DNS management rights over a specific subdomain. Can only be called by the parent token owner. **Parameters** | Name | Type | Description | | ------------- | ------- | ------------------------------------------------------------------------ | | parentTokenId | uint256 | The ID of the parent synthetic token. | | host | string | The subdomain host label (eg "sam", "dev", "app"). | | capabilities | uint256 | Capability flags (must include CAPABILITY\_DNS\_RECORDS\_MANAGEMENT). | | expiresAt | uint256 | Expiration timestamp for the subdomain token (0 to inherit from parent). | | revocable | bool | Whether the parent token owner can revoke this subdomain. | | groupId | uint256 | Group identifier for batch operations (batch revoke). | | receiver | address | The address to receive the minted subdomain token. | #### **Return Values** | Name | Type | Description | | ---- | ------- | --------------------------------------------- | | \[0] | uint256 | The newly minted synthetic subdomain token ID | #### renewSubdomain ```solidity function renewSubdomain(uint256 tokenId, uint256 expiresAt) external payable ``` Renew a synthetic subdomain token. Can only be called by the parent token owner. New expiration must extend the current expiration and must not exceed the parent token's expiration. **Parameters** | Name | Type | Description | | --------- | ------- | --------------------------------------- | | tokenId | uint256 | The ID of the subdomain token to renew. | | expiresAt | uint256 | The new expiration timestamp. | #### renounceSynthetic ```solidity function renounceSynthetic(uint256 tokenId) external ``` Renounce ownership of a synthetic subdomain token. Burns the subdomain token and makes it available for re-minting. Can only be called by the subdomain token owner. The subdomain must not be in a locked group. **Parameters** | Name | Type | Description | | ------- | ------- | ------------------------------------------ | | tokenId | uint256 | The ID of the subdomain token to renounce. | #### revokeSynthetic ```solidity function revokeSynthetic(uint256 tokenId) external ``` Revoke a specific synthetic subdomain token. Burns the subdomain token and makes it available for re-minting. Can only be called by the parent token owner. The subdomain must be revocable and not in a locked group. **Parameters** | Name | Type | Description | | ------- | ------- | ---------------------------------------- | | tokenId | uint256 | The ID of the subdomain token to revoke. | #### revokeGroup ```solidity function revokeGroup(uint256 parentTokenId, uint256 groupId) external ``` Revoke a group of subdomains, preventing transfers and marking them for bulk operations. Can only be called by the parent token owner. Reduces the parent's subdomain count by the number of tokens in the group. **Parameters** | Name | Type | Description | | ------------- | ------- | ------------------------------------- | | parentTokenId | uint256 | The ID of the parent synthetic token. | | groupId | uint256 | The group identifier to revoke. | #### version ```solidity function version() external pure returns (string) ``` Get the contract version. **Return Values** | Name | Type | Description | | ---- | ------ | ----------------------------------- | | \[0] | string | The version string of this contract | #### REQUEST\_TOKENIZATION\_OPERATION ```solidity function REQUEST_TOKENIZATION_OPERATION() external pure returns (bytes32) ``` Get the REQUEST\_TOKENIZATION\_OPERATION constant **Return Values** | Name | Type | Description | | ---- | ------- | ------------------------------------------- | | \[0] | bytes32 | The operation hash for request tokenization | #### CLAIM\_OWNERSHIP\_OPERATION ```solidity function CLAIM_OWNERSHIP_OPERATION() external pure returns (bytes32) ``` Get the CLAIM\_OWNERSHIP\_OPERATION constant **Return Values** | Name | Type | Description | | ---- | ------- | -------------------------------------- | | \[0] | bytes32 | The operation hash for claim ownership | #### BRIDGE\_OPERATION ```solidity function BRIDGE_OPERATION() external pure returns (bytes32) ``` Get the BRIDGE\_OPERATION constant **Return Values** | Name | Type | Description | | ---- | ------- | ----------------------------- | | \[0] | bytes32 | The operation hash for bridge | #### SET\_NAMESERVERS\_OPERATION ```solidity function SET_NAMESERVERS_OPERATION() external pure returns (bytes32) ``` Get the SET\_NAMESERVERS\_OPERATION constant **Return Values** | Name | Type | Description | | ---- | ------- | -------------------------------------- | | \[0] | bytes32 | The operation hash for set nameservers | #### SET\_DS\_KEYS\_OPERATION ```solidity function SET_DS_KEYS_OPERATION() external pure returns (bytes32) ``` Get the SET\_DS\_KEYS\_OPERATION constant **Return Values** | Name | Type | Description | | ---- | ------- | ---------------------------------- | | \[0] | bytes32 | The operation hash for set DS keys | #### SET\_DNS\_RRSET\_OPERATION ```solidity function SET_DNS_RRSET_OPERATION() external pure returns (bytes32) ``` Get the SET\_DNS\_RRSET\_OPERATION constant **Return Values** | Name | Type | Description | | ---- | ------- | ------------------------------------ | | \[0] | bytes32 | The operation hash for set DNS RRSet | #### CONVERT\_TO\_SYNTHETIC\_OPERATION ```solidity function CONVERT_TO_SYNTHETIC_OPERATION() external pure returns (bytes32) ``` Get the CONVERT\_TO\_SYNTHETIC\_OPERATION constant **Return Values** | Name | Type | Description | | ---- | ------- | -------------------------------------------- | | \[0] | bytes32 | The operation hash for convert to synthetic. | #### CONVERT\_TO\_OWNERSHIP\_OPERATION ```solidity function CONVERT_TO_OWNERSHIP_OPERATION() external pure returns (bytes32) ``` Get the CONVERT\_TO\_OWNERSHIP constant **Return Values** | Name | Type | Description | | ---- | ------- | -------------------------------------------- | | \[0] | bytes32 | The operation hash for convert to ownership. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.doma.xyz/api-reference/doma-smart-contracts-api/evm-proxy-doma-record-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.