(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.

119KB

ProxyDomaRecordUserFacet.json

Open

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.

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)

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

Name	Type	Description
host	string	The hostname relative to the token (eg. "www" or "" for apex). Must be lowercase.
recordSets	struct IDomaRecord.DNSRecordSet[]	Array of DNS record sets for this host.

struct HostDNSInput {                                                                                                                                                                                                                       
    string host;                                     
    struct IDomaRecord.DNSRecordSet[] recordSets;
  }

DNSRecordSet

A single DNS record set containing a record type, TTL and values.

Parameters

Name	Type	Description
recordType	string	DNS record type (eg "A", "AAAA", "CNAME").
ttl	uint32	Time to live in seconds.
records	string[]	Array of record values. Empty array deletes the RRSet.

struct DNSRecordSet {
    string recordType;                                                                                                                                                                                                                        
    uint32 ttl;                                      
    string[] records;                                                                                                                                                                                                                         
  }   

Errors

InsufficientCapabilities

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

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

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

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

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

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

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

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

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

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

error TransferFailed()

Thrown when a native currency transfer fails.

InvalidFee

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

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

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

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

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

error EmptyArray()

Thrown when an empty array is passed to a batch operation.

Methods

requestTokenization

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.