From cd938302eaee58dc9b4aaa529d43bea727ab9948 Mon Sep 17 00:00:00 2001 From: James Earle Date: Thu, 2 Nov 2023 12:11:27 -0700 Subject: [PATCH 1/2] regenerate documentation --- docs/contracts/access/AccessControlled.md | 94 ----- .../contracts/distribution/IZNSPriceOracle.md | 306 --------------- docs/contracts/distribution/IZNSRegistrar.md | 260 ------------- docs/contracts/distribution/IZNSTreasury.md | 197 ---------- docs/contracts/distribution/ZNSPriceOracle.md | 354 ------------------ docs/contracts/distribution/ZNSRegistrar.md | 329 ---------------- docs/contracts/distribution/ZNSTreasury.md | 256 ------------- docs/contracts/price/IZNSCurvePricer.md | 11 +- docs/contracts/price/IZNSFixedPricer.md | 24 +- docs/contracts/price/ZNSCurvePricer.md | 44 ++- docs/contracts/price/ZNSFixedPricer.md | 66 +++- docs/contracts/registrar/IZNSSubRegistrar.md | 40 +- docs/contracts/registrar/ZNSRootRegistrar.md | 24 +- docs/contracts/registrar/ZNSSubRegistrar.md | 85 ++++- docs/contracts/registry/IZNSRegistry.md | 62 --- docs/contracts/registry/ZNSRegistry.md | 19 +- .../contracts/resolver/IZNSAddressResolver.md | 26 -- docs/contracts/resolver/ZNSAddressResolver.md | 12 + docs/contracts/token/ZNSDomainToken.md | 28 +- docs/contracts/treasury/ZNSTreasury.md | 50 ++- docs/contracts/types/ICurvePriceConfig.md | 1 + docs/contracts/types/IDistributionConfig.md | 6 +- docs/contracts/types/IZNSPricer.md | 11 +- 23 files changed, 345 insertions(+), 1960 deletions(-) delete mode 100644 docs/contracts/access/AccessControlled.md delete mode 100644 docs/contracts/distribution/IZNSPriceOracle.md delete mode 100644 docs/contracts/distribution/IZNSRegistrar.md delete mode 100644 docs/contracts/distribution/IZNSTreasury.md delete mode 100644 docs/contracts/distribution/ZNSPriceOracle.md delete mode 100644 docs/contracts/distribution/ZNSRegistrar.md delete mode 100644 docs/contracts/distribution/ZNSTreasury.md diff --git a/docs/contracts/access/AccessControlled.md b/docs/contracts/access/AccessControlled.md deleted file mode 100644 index 8bd578960..000000000 --- a/docs/contracts/access/AccessControlled.md +++ /dev/null @@ -1,94 +0,0 @@ -## AccessControlled - - -**This abstract contract outlines basic functionality, declares functions -that need to be implemented to provide a deterministic connection to `ZNSAccessController` module.** - - - -In order to connect an arbitrary module to `ZNSAccessController` and it's functionality, -this contract needs to be inherited by the module. - - - -### AccessControllerSet - -```solidity -event AccessControllerSet(address accessController) -``` - - -Emitted when the access controller contract address is set. - - - - -### accessController - -```solidity -contract IZNSAccessController accessController -``` - - -Address of the ZNSAccessController contract. - - - - -### onlyAdmin - -```solidity -modifier onlyAdmin() -``` - - -Modifier to make a function callable only when caller is an admin. -Implemented here to avoid declaring this in every single contract that uses it. - - - - -### getAccessController - -```solidity -function getAccessController() external view virtual returns (address) -``` - - -Virtual function to make sure the getter is always implemented in children, -otherwise we will not be able to read the AC address in children - - - - -### setAccessController - -```solidity -function setAccessController(address _accessController) external virtual -``` - - -Virtual function to make sure the setter is always implemented in children, -otherwise we will not be able to reset the AC address in children - - - - -### _setAccessController - -```solidity -function _setAccessController(address _accessController) internal -``` - - -Internal function to set the access controller address. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _accessController | address | Address of the ZNSAccessController contract. | - - - diff --git a/docs/contracts/distribution/IZNSPriceOracle.md b/docs/contracts/distribution/IZNSPriceOracle.md deleted file mode 100644 index 29f33335c..000000000 --- a/docs/contracts/distribution/IZNSPriceOracle.md +++ /dev/null @@ -1,306 +0,0 @@ -## IZNSPriceOracle - - - - - -**`DomainPriceConfig` struct properties:** - -- `maxPrice` (uint256): Maximum price for a domain returned at <= `baseLength` -- `minPrice` (uint256): Minimum price for a domain returned at > `maxLength` -- `maxLength` (uint256): Maximum length of a domain name. If the name is longer than this value we return the `minPrice` -- `baseLength` (uint256): Base length of a domain name. If the name is less than or equal to this value we return the `maxPrice` -- `precisionMultiplier` (uint256): The precision multiplier of the price. This multiplier -should be picked based on the number of token decimals to calculate properly. -e.g. if we use a token with 18 decimals, and want precision of 2, -our precision multiplier will be equal 10^18 - 10^2 = 10^16 - - - -### MaxPriceSet - -```solidity -event MaxPriceSet(uint256 price) -``` - - -Emitted when the `maxPrice` is set in `rootDomainPriceConfig` - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| price | uint256 | The new maxPrice value | - - -### MinPriceSet - -```solidity -event MinPriceSet(uint256 price) -``` - - -Emitted when the `minPrice` is set in `rootDomainPriceConfig` - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| price | uint256 | The new minPrice value | - - -### BaseLengthSet - -```solidity -event BaseLengthSet(uint256 length) -``` - - -Emitted when the `baseLength` is set in `rootDomainPriceConfig` - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| length | uint256 | The new baseLength value | - - -### MaxLengthSet - -```solidity -event MaxLengthSet(uint256 length) -``` - - -Emitted when the `maxLength` is set in `rootDomainPriceConfig` - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| length | uint256 | The new maxLength value | - - -### PrecisionMultiplierSet - -```solidity -event PrecisionMultiplierSet(uint256 precision) -``` - - -Emitted when the `precisionMultiplier` is set in `rootDomainPriceConfig` - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| precision | uint256 | The new precisionMultiplier value | - - -### FeePercentageSet - -```solidity -event FeePercentageSet(uint256 feePercentage) -``` - - -Emitted when the `feePercentage` is set in state - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| feePercentage | uint256 | The new feePercentage value | - - -### PriceConfigSet - -```solidity -event PriceConfigSet(uint256 maxPrice, uint256 minPrice, uint256 maxLength, uint256 baseLength, uint256 precisionMultiplier) -``` - - -Emitted when the full `rootDomainPriceConfig` is set in state - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maxPrice | uint256 | The new `maxPrice` value | -| minPrice | uint256 | The new `minPrice` value | -| maxLength | uint256 | The new `maxLength` value | -| baseLength | uint256 | The new `baseLength` value | -| precisionMultiplier | uint256 | The new `precisionMultiplier` value | - - -### DomainPriceConfig - - - - - - - - -```solidity -struct DomainPriceConfig { - uint256 maxPrice; - uint256 minPrice; - uint256 maxLength; - uint256 baseLength; - uint256 precisionMultiplier; -} -``` - -### initialize - -```solidity -function initialize(address accessController_, struct IZNSPriceOracle.DomainPriceConfig priceConfig_, uint256 regFeePercentage_) external -``` - - - - - - - -### getPrice - -```solidity -function getPrice(string name) external view returns (uint256 totalPrice, uint256 domainPrice, uint256 fee) -``` - - - - - - - -### getRegistrationFee - -```solidity -function getRegistrationFee(uint256 domainPrice) external view returns (uint256) -``` - - - - - - - -### setPriceConfig - -```solidity -function setPriceConfig(struct IZNSPriceOracle.DomainPriceConfig priceConfig) external -``` - - - - - - - -### setMaxPrice - -```solidity -function setMaxPrice(uint256 maxPrice) external -``` - - - - - - - -### setMinPrice - -```solidity -function setMinPrice(uint256 minPrice) external -``` - - - - - - - -### setBaseLength - -```solidity -function setBaseLength(uint256 length) external -``` - - - - - - - -### setMaxLength - -```solidity -function setMaxLength(uint256 length) external -``` - - - - - - - -### setPrecisionMultiplier - -```solidity -function setPrecisionMultiplier(uint256 multiplier) external -``` - - - - - - - -### setRegistrationFeePercentage - -```solidity -function setRegistrationFeePercentage(uint256 regFeePercentage) external -``` - - - - - - - -### setAccessController - -```solidity -function setAccessController(address accessController) external -``` - - - - - - - -### getAccessController - -```solidity -function getAccessController() external view returns (address) -``` - - - - - - - - diff --git a/docs/contracts/distribution/IZNSRegistrar.md b/docs/contracts/distribution/IZNSRegistrar.md deleted file mode 100644 index bc718d181..000000000 --- a/docs/contracts/distribution/IZNSRegistrar.md +++ /dev/null @@ -1,260 +0,0 @@ -## IZNSRegistrar - - - - - - - - -### DomainRegistered - -```solidity -event DomainRegistered(bytes32 domainHash, uint256 tokenId, string name, address registrant, address resolver, address domainAddress) -``` - - -Emitted when a NEW domain is registered. - -`domainAddress` parameter is the address to which a domain name will relate to in ZNS. -E.g. if a user made a domain for his wallet, the address of the wallet will be the `domainAddress`. -This can be 0 as this variable is not required to perform registration process -and can be set at a later time by the domain owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain registered | -| tokenId | uint256 | The tokenId of the domain registered | -| name | string | The name as string of the domain registered | -| registrant | address | The address that called `ZNSRegistrar.registerDomain()` | -| resolver | address | The resolver contract address of the domain registered | -| domainAddress | address | The domain address of the domain registered | - - -### DomainRevoked - -```solidity -event DomainRevoked(bytes32 domainHash, address registrant) -``` - - -Emitted when a domain is revoked. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain revoked | -| registrant | address | The address that called `ZNSRegistrar.revokeDomain()` | - - -### DomainReclaimed - -```solidity -event DomainReclaimed(bytes32 domainHash, address registrant) -``` - - -Emitted when an ownership of the Name is reclaimed by the Token owner. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain reclaimed | -| registrant | address | The address that called `ZNSRegistrar.reclaimDomain()` | - - -### RegistrySet - -```solidity -event RegistrySet(address registry) -``` - - -Emitted when the `registry` address is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| registry | address | The new address of the registry contract | - - -### TreasurySet - -```solidity -event TreasurySet(address treasury) -``` - - -Emitted when the `treasury` address is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| treasury | address | The new address of the treasury contract | - - -### DomainTokenSet - -```solidity -event DomainTokenSet(address domainToken) -``` - - -Emitted when the `domainToken` address is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainToken | address | The new address of the domainToken contract | - - -### AddressResolverSet - -```solidity -event AddressResolverSet(address addressResolver) -``` - - -Emitted when the `addressResolver` address is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| addressResolver | address | The new address of the addressResolver contract | - - -### registerDomain - -```solidity -function registerDomain(string name, address resolverContent) external returns (bytes32) -``` - - - - - - - -### revokeDomain - -```solidity -function revokeDomain(bytes32 domainHash) external -``` - - - - - - - -### reclaimDomain - -```solidity -function reclaimDomain(bytes32 domainHash) external -``` - - - - - - - -### setRegistry - -```solidity -function setRegistry(address registry_) external -``` - - - - - - - -### setTreasury - -```solidity -function setTreasury(address treasury_) external -``` - - - - - - - -### setDomainToken - -```solidity -function setDomainToken(address domainToken_) external -``` - - - - - - - -### setAddressResolver - -```solidity -function setAddressResolver(address addressResolver_) external -``` - - - - - - - -### setAccessController - -```solidity -function setAccessController(address accessController_) external -``` - - - - - - - -### getAccessController - -```solidity -function getAccessController() external view returns (address) -``` - - - - - - - -### initialize - -```solidity -function initialize(address accessController_, address registry_, address treasury_, address domainToken_, address addressResolver_) external -``` - - - - - - - - diff --git a/docs/contracts/distribution/IZNSTreasury.md b/docs/contracts/distribution/IZNSTreasury.md deleted file mode 100644 index f4c341d83..000000000 --- a/docs/contracts/distribution/IZNSTreasury.md +++ /dev/null @@ -1,197 +0,0 @@ -## IZNSTreasury - - - - - - - - -### StakeDeposited - -```solidity -event StakeDeposited(bytes32 domainHash, string domainName, address depositor, uint256 stakeAmount, uint256 registrationFee) -``` - - -Emitted when a new stake is deposited upon registration of a new domain. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain name | -| domainName | string | The domain name as a string | -| depositor | address | The address of the depositing user / new domain owner | -| stakeAmount | uint256 | The amount they are depositing / price of the domain based on name length | -| registrationFee | uint256 | The registration fee paid by the user on top of the staked amount | - - -### StakeWithdrawn - -```solidity -event StakeWithdrawn(bytes32 domainHash, address owner, uint256 stakeAmount) -``` - - -Emitted when a stake is withdrawn upon domain revocation. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain name being revoked | -| owner | address | The owner of the domain being revoked | -| stakeAmount | uint256 | The staked amount withdrawn to the user after revoking | - - -### PriceOracleSet - -```solidity -event PriceOracleSet(address priceOracle) -``` - - -Emitted when `priceOracle` is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| priceOracle | address | The new address of the price oracle contract | - - -### StakingTokenSet - -```solidity -event StakingTokenSet(address stakingToken) -``` - - -Emitted when `stakingToken` is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| stakingToken | address | The new address of the ERC-20 compliant staking token contract | - - -### ZeroVaultAddressSet - -```solidity -event ZeroVaultAddressSet(address zeroVault) -``` - - -Emitted when `zeroVault` is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| zeroVault | address | The new address of the zero vault contract or wallet | - - -### stakeForDomain - -```solidity -function stakeForDomain(bytes32 domainHash, string domainName, address depositor) external -``` - - - - - - - -### unstakeForDomain - -```solidity -function unstakeForDomain(bytes32 domainHash, address owner) external -``` - - - - - - - -### setZeroVaultAddress - -```solidity -function setZeroVaultAddress(address zeroVaultAddress) external -``` - - - - - - - -### setPriceOracle - -```solidity -function setPriceOracle(address priceOracle_) external -``` - - - - - - - -### setStakingToken - -```solidity -function setStakingToken(address stakingToken_) external -``` - - - - - - - -### setAccessController - -```solidity -function setAccessController(address accessController) external -``` - - - - - - - -### getAccessController - -```solidity -function getAccessController() external view returns (address) -``` - - - - - - - -### initialize - -```solidity -function initialize(address accessController_, address priceOracle_, address stakingToken_, address zeroVault_) external -``` - - - - - - - - diff --git a/docs/contracts/distribution/ZNSPriceOracle.md b/docs/contracts/distribution/ZNSPriceOracle.md deleted file mode 100644 index 16c83250f..000000000 --- a/docs/contracts/distribution/ZNSPriceOracle.md +++ /dev/null @@ -1,354 +0,0 @@ -## ZNSPriceOracle - - -**Implementation of the Price Oracle, module that calculates the price of a domain -based on its length and the rules set by Zero ADMIN.** - - - - - - -### PERCENTAGE_BASIS - -```solidity -uint256 PERCENTAGE_BASIS -``` - - -Value used as a basis for percentage calculations, -since Solidity does not support fractions. - - - - -### rootDomainPriceConfig - -```solidity -struct IZNSPriceOracle.DomainPriceConfig rootDomainPriceConfig -``` - - -Struct for each configurable price variable -that participates in the price calculation. - -See [IZNSPriceOracle.md](./IZNSPriceOracle.md) for more details. - - - -### feePercentage - -```solidity -uint256 feePercentage -``` - - -The registration fee value in percentage as basis points (parts per 10,000) - so the 2% value would be represented as 200. - See [getRegistrationFee](#getregistrationfee) for the actual fee calc process. - - - - -### initialize - -```solidity -function initialize(address accessController_, struct IZNSPriceOracle.DomainPriceConfig priceConfig_, uint256 regFeePercentage_) public -``` - - -Proxy initializer to set the initial state of the contract after deployment. -Only ADMIN can call this function. - -> Note the for DomainPriceConfig we set each value individually and calling -2 important functions that validate all of the config's values against the formula: -- `setPrecisionMultiplier()` to validate precision multiplier -- `_validateConfig()` to validate the whole config in order to avoid price spikes - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController_ | address | the address of the ZNSAccessController contract. | -| priceConfig_ | struct IZNSPriceOracle.DomainPriceConfig | a number of variables that participate in the price calculation. | -| regFeePercentage_ | uint256 | the registration fee value in percentage as basis points (parts per 10,000) | - - -### getPrice - -```solidity -function getPrice(string name) external view returns (uint256 totalPrice, uint256 domainPrice, uint256 fee) -``` - - -Get the price of a given domain name - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| name | string | The name of the domain to check | - - -### getRegistrationFee - -```solidity -function getRegistrationFee(uint256 domainPrice) public view returns (uint256) -``` - - -Get the registration fee amount in `stakingToken` for a specific domain price -as `domainPrice * feePercentage / PERCENTAGE_BASIS`. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainPrice | uint256 | The price of the domain | - - -### setPriceConfig - -```solidity -function setPriceConfig(struct IZNSPriceOracle.DomainPriceConfig priceConfig) external -``` - - -Setter for `rootDomainPriceConfig`. Only ADMIN can call this function. - -Validates the value of the `precisionMultiplier` and the whole config in order to avoid price spikes, -fires `PriceConfigSet` event. -Only ADMIN can call this function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| priceConfig | struct IZNSPriceOracle.DomainPriceConfig | The new price config to set | - - -### setMaxPrice - -```solidity -function setMaxPrice(uint256 maxPrice) external -``` - - -Sets the max price for domains. Validates the config with the new price. -Fires `MaxPriceSet` event. -Only ADMIN can call this function. -> `maxPrice` can be set to 0 to make all domains free! - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maxPrice | uint256 | The maximum price to set in $ZERO | - - -### setMinPrice - -```solidity -function setMinPrice(uint256 minPrice) external -``` - - -Sets the minimum price for domains. Validates the config with the new price. -Fires `MinPriceSet` event. -Only ADMIN can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| minPrice | uint256 | The minimum price to set in $ZERO | - - -### setBaseLength - -```solidity -function setBaseLength(uint256 length) external -``` - - -Set the value of the domain name length boundary where the `maxPrice` applies -e.g. A value of '5' means all domains <= 5 in length cost the `maxPrice` price -Validates the config with the new length. Fires `BaseLengthSet` event. -Only ADMIN can call this function. -> `baseLength` can be set to 0 to make all domains cost `maxPrice`! -> This indicates to the system that we are -> currently in a special phase where we define an exact price for all domains -> e.g. promotions or sales - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| length | uint256 | Boundary to set | - - -### setMaxLength - -```solidity -function setMaxLength(uint256 length) external -``` - - -Set the maximum length of a domain name to which price formula applies. -All domain names (labels) that are longer than this value will cost the fixed price of `minPrice`, -and the pricing formula will not apply to them. -Validates the config with the new length. -Fires `MaxLengthSet` event. -Only ADMIN can call this function. -> `maxLength` can be set to 0 to make all domains cost `minPrice`! - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| length | uint256 | The maximum length to set | - - -### setPrecisionMultiplier - -```solidity -function setPrecisionMultiplier(uint256 multiplier) public -``` - - -Sets the precision multiplier for the price calculation. -Multiplier This should be picked based on the number of token decimals -to calculate properly. -e.g. if we use a token with 18 decimals, and want precision of 2, -our precision multiplier will be equal to `10^(18 - 2) = 10^16` -Fires `PrecisionMultiplierSet` event. -Only ADMIN can call this function. -> Multiplier should be less or equal to 10^18 and greater than 0! - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| multiplier | uint256 | The multiplier to set | - - -### setRegistrationFeePercentage - -```solidity -function setRegistrationFeePercentage(uint256 regFeePercentage) external -``` - - -Sets the fee percentage for domain registration. - -Fee percentage is set according to the basis of 10000, outlined in ``PERCENTAGE_BASIS``. -Fires ``FeePercentageSet`` event. -Only ADMIN can call this function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| regFeePercentage | uint256 | The fee percentage to set | - - -### setAccessController - -```solidity -function setAccessController(address accessController_) external -``` - - -Sets the access controller for the contract. -Only ADMIN can call this function. -Fires `AccessControllerSet` event. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController_ | address | The address of the new access controller | - - -### getAccessController - -```solidity -function getAccessController() external view returns (address) -``` - - -Getter for ZNSAccessController address stored on this contract. - - - - -### _getPrice - -```solidity -function _getPrice(uint256 length) internal view returns (uint256) -``` - - -Internal function to calculate price based on the config set, -and the length of the domain label. - -Before we calculate the price, 3 different cases are possible: -1. `baseLength` is 0, which means we are returning `maxPrice` as a specific price for all domains -2. `length` is less than or equal to `baseLength`, which means a domain will cost `maxPrice` -3. `length` is greater than `maxLength`, which means a domain will cost `minPrice` - -The formula itself creates an asymptotic curve that decreases in pricing based on domain name length, -base length and max price, the result is divided by the precision multiplier to remove numbers beyond -what we care about, then multiplied by the same precision multiplier to get the actual value -with truncated values past precision. So having a value of `15.235234324234512365 * 10^18` -with precision `2` would give us `15.230000000000000000 * 10^18` - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| length | uint256 | The length of the domain name | - - -### _validateConfig - -```solidity -function _validateConfig() internal view -``` - - -Internal function called every time we set props of `rootDomainPriceConfig` -to make sure that values being set can not disrupt the price curve or zero out prices -for domains. If this validation fails, function will revert. - -We are checking here for possible price spike at `maxLength` -which can occur if some of the config values are not properly chosen and set. - - - -### _authorizeUpgrade - -```solidity -function _authorizeUpgrade(address newImplementation) internal view -``` - - -To use UUPS proxy we override this function and revert if `msg.sender` isn't authorized - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| newImplementation | address | The new implementation contract to upgrade to. | - - - diff --git a/docs/contracts/distribution/ZNSRegistrar.md b/docs/contracts/distribution/ZNSRegistrar.md deleted file mode 100644 index 4a4102373..000000000 --- a/docs/contracts/distribution/ZNSRegistrar.md +++ /dev/null @@ -1,329 +0,0 @@ -## ZNSRegistrar - - -**Main entry point for the three main flows of ZNS - Register, Reclaim and Revoke a domain.** - -This contract serves as the "umbrella" for many ZNS operations, it is given REGISTRAR_ROLE -to combine multiple calls/operations between different modules to achieve atomic state changes -and proper logic for the ZNS flows. You can see functions in other modules that are only allowed -to be called by this contract to ensure proper management of ZNS data in multiple places. -RRR - Register, Reclaim, Revoke start here and then call other modules to complete the flow. -ZNSRegistrar stores most of the other contract addresses and can communicate with other modules, -but the relationship is one-sided, where other modules do not need to know about the ZNSRegistrar, -they only check REGISTRAR_ROLE that can, in theory, be assigned to any other address. - - - - -### registry - -```solidity -contract IZNSRegistry registry -``` - - - - - - - -### treasury - -```solidity -contract IZNSTreasury treasury -``` - - - - - - - -### domainToken - -```solidity -contract IZNSDomainToken domainToken -``` - - - - - - - -### addressResolver - -```solidity -contract IZNSAddressResolver addressResolver -``` - - - - - - - -### onlyNameOwner - -```solidity -modifier onlyNameOwner(bytes32 domainHash) -``` - - -Ensures only the owner of the Name in ZNSRegistry can call. - - - - -### onlyTokenOwner - -```solidity -modifier onlyTokenOwner(bytes32 domainHash) -``` - - -Ensures only the owner of the Tame in ZNSDomainToken can call. - - - - -### initialize - -```solidity -function initialize(address accessController_, address registry_, address treasury_, address domainToken_, address addressResolver_) public -``` - - -Create an instance of the ZNSRegistrar -for registering, reclaiming and revoking ZNS domains - -Instead of direct assignments, we are calling the setter functions -to apply Access Control and ensure only the ADMIN can set the addresses. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController_ | address | Address of the ZNSAccessController contract | -| registry_ | address | Address of the ZNSRegistry contract | -| treasury_ | address | Address of the ZNSTreasury contract | -| domainToken_ | address | Address of the ZNSDomainToken contract | -| addressResolver_ | address | Address of the ZNSAddressResolver contract | - - -### registerDomain - -```solidity -function registerDomain(string name, address domainAddress) external returns (bytes32) -``` - - -This function is the main entry point for the Register flow. -Registers a new domain such as `0://wilder`. -Gets domain hash as a keccak256 hash of the domain label string casted to bytes32, -checks existence of the domain in the registry and reverts if it exists. -Calls `ZNSTreasury` to do the staking part, gets `tokenId` for the new token to be minted -as domain hash casted to uint256, mints the token and sets the domain data in the `ZNSRegistry` -and, possibly, `ZNSAddressResolver`. Emits a `DomainRegistered` event. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| name | string | Name (label) of the domain to register | -| domainAddress | address | Address for the `ZNSAddressResolver` to return when requested (optional, send 0x0 if not needed) | - - -### revokeDomain - -```solidity -function revokeDomain(bytes32 domainHash) external -``` - - -This function is the main entry point for the Revoke flow. -Revokes a domain such as `0://wilder`. -Gets `tokenId` from casted domain hash to uint256, calls `ZNSDomainToken` to burn the token, -deletes the domain data from the `ZNSRegistry` and calls `ZNSTreasury` to unstake and withdraw funds -user staked for the domain. Emits a `DomainRevoked` event. - -> Note that we are not clearing the data in `ZNSAddressResolver` as it is considered not necessary -since none other contracts will have the domain data on them. -If we are not clearing `ZNSAddressResolver` state slots, we are making the next Register transaction -for the same name cheaper, since SSTORE on a non-zero slot costs 5k gas, while SSTORE on a zero slot costs 20k gas. -If a user wants to clear his data from `ZNSAddressResolver`, he can call `ZNSAddressResolver` directly himself -BEFORE he calls to revoke, otherwise, `ZNSRegistry` owner check will fail, since the owner there -will be 0x0 address. -Also note that in order to Revoke, a caller has to be the owner of both: -Name (in `ZNSRegistry`) and Token (in `ZNSDomainToken`). - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | Hash of the domain to revoke | - - -### reclaimDomain - -```solidity -function reclaimDomain(bytes32 domainHash) external -``` - - -This function is the main entry point for the Reclaim flow. This flow is used to -reclaim full ownership of a domain (through becoming the owner of the Name) from the ownership of the Token. -This is used for different types of ownership transfers, such as: -- domain sale - a user will sell the Token, then the new owner has to call this function to reclaim the Name -- domain transfer - a user will transfer the Token, then the new owner has to call this function to reclaim the Name - -A user needs to only be the owner of the Token to be able to Reclaim. -Updates the domain owner in the `ZNSRegistry` to the owner of the token and emits a `DomainReclaimed` event. - - - - -### setRegistry - -```solidity -function setRegistry(address registry_) public -``` - - -Setter function for the `ZNSRegistry` address in state. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| registry_ | address | Address of the `ZNSRegistry` contract | - - -### setTreasury - -```solidity -function setTreasury(address treasury_) public -``` - - -Setter function for the `ZNSTreasury` address in state. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| treasury_ | address | Address of the `ZNSTreasury` contract | - - -### setDomainToken - -```solidity -function setDomainToken(address domainToken_) public -``` - - -Setter function for the `ZNSDomainToken` address in state. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainToken_ | address | Address of the `ZNSDomainToken` contract | - - -### setAddressResolver - -```solidity -function setAddressResolver(address addressResolver_) public -``` - - -Setter function for the `ZNSAddressResolver` address in state. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| addressResolver_ | address | Address of the `ZNSAddressResolver` contract | - - -### setAccessController - -```solidity -function setAccessController(address accessController_) external -``` - - -Setter function for the `ZNSAccessController` address in state. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController_ | address | Address of the `ZNSAccessController` contract | - - -### getAccessController - -```solidity -function getAccessController() external view returns (address) -``` - - -Getter function for the `ZNSAccessController` address in state. - - - - -### _setDomainData - -```solidity -function _setDomainData(bytes32 domainHash, address owner, address domainAddress) internal -``` - - -Set domain data appropriately for a newly registered domain -If no domain address is given, only the domain owner is set, otherwise -`ZNSAddressResolver` is called to assign an address to the newly registered domain. -If the `domainAddress` is not provided upon registration, a user can call `ZNSAddressResolver.setAddress` -to set the address themselves. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The domain name hash | -| owner | address | The owner of the domain | -| domainAddress | address | The content (source) it resolves to | - - -### _authorizeUpgrade - -```solidity -function _authorizeUpgrade(address newImplementation) internal view -``` - - -To use UUPS proxy we override this function and revert if `msg.sender` isn't authorized - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| newImplementation | address | The implementation contract to upgrade to | - - - diff --git a/docs/contracts/distribution/ZNSTreasury.md b/docs/contracts/distribution/ZNSTreasury.md deleted file mode 100644 index 1dbb84f29..000000000 --- a/docs/contracts/distribution/ZNSTreasury.md +++ /dev/null @@ -1,256 +0,0 @@ -## ZNSTreasury - - -**Contract responsible for all staking operations in ZNS and communication with `ZNSPriceOracle`.** - -This contract it called by `ZNSRegistrar` every time a staking operation is needed. -It stores all data regarding user stakes for domains, and it's also the only contract -that is aware of the `ZNSPriceOracle` which it uses to get pricing data for domains. - - - - -### priceOracle - -```solidity -contract IZNSPriceOracle priceOracle -``` - - -The address of the `ZNSPriceOracle` contract. - - - - -### stakingToken - -```solidity -contract IERC20 stakingToken -``` - - -The address of the payment/staking token. Will be set to $ZERO. - - - - -### zeroVault - -```solidity -address zeroVault -``` - - -Address of the Zero Vault, a wallet or contract which gathers all the registration fees. - - - - -### stakedForDomain - -```solidity -mapping(bytes32 => uint256) stakedForDomain -``` - - -The main mapping of the contract. It stores the amount staked for each domain -which is mapped to the domain hash. -Note that there is no address to which the stake is tied to. Instead, the owner data from `ZNSRegistry` -is used to identify a user who owns the stake. So the staking data is tied to the owner of the Name. -This should be taken into account, since any transfer of the Token to another address, -and the system, allowing them to Reclaim the Name, will also allow them to withdraw the stake. -> Stake is owned by the owner of the Name in `ZNSRegistry`! - - - - -### onlyRegistrar - -```solidity -modifier onlyRegistrar() -``` - - -Modifier used for functions that are only allowed to be called by the `ZNSRegistrar` -or any other address that has REGISTRAR_ROLE. - - - - -### initialize - -```solidity -function initialize(address accessController_, address priceOracle_, address stakingToken_, address zeroVault_) external -``` - - -`ZNSTreasury` proxy state initializer. Note that setter functions are used -instead of direct state variable assignments in order to use proper Access Control -at initialization. Only ADMIN in `ZNSAccessController` can call this function. -For this also, it is important that `ZNSAccessController` is deployed and initialized with role data -before this contract is deployed. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController_ | address | The address of the `ZNSAccessController` contract. | -| priceOracle_ | address | The address of the `ZNSPriceOracle` contract. | -| stakingToken_ | address | The address of the staking token (currently $ZERO). | -| zeroVault_ | address | The address of the Zero Vault - the wallet or contract to collect all the registration fees. | - - -### stakeForDomain - -```solidity -function stakeForDomain(bytes32 domainHash, string domainName, address depositor) external -``` - - -Deposits the stake for a domain. This function is called by `ZNSRegistrar` -when a user wants to Register a domain. It transfers the stake amount and the registration fee -to the contract from the user, and records the staked amount for the domain. -Note that a user has to approve the correct amount of `domainPrice + registrationFee` -for this function to not revert. - -Calls `ZNSPriceOracle` to get the price for the domain name based on it's length, -and to get a proper `registrationFee` as a percentage of the price. -In order to avoid needing 2 different approvals, it withdraws `domainPrice + registrationFee` -to this contract and then transfers the `registrationFee` to the Zero Vault. -Sets the `stakedForDomain` mapping for the domain to the `stakeAmount` and emits a `StakeDeposited` event. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain for which the stake is being deposited. | -| domainName | string | The name of the domain for which the stake is being deposited. | -| depositor | address | The address of the user who is depositing the stake. | - - -### unstakeForDomain - -```solidity -function unstakeForDomain(bytes32 domainHash, address owner) external -``` - - -Withdraws the stake for a domain. This function is called by `ZNSRegistrar` -when a user wants to Revoke a domain. It transfers the stake amount from the contract back to the user, -and deletes the staked amount for the domain in state. -Emits a `StakeWithdrawn` event. -Since we are clearing a slot in storage, gas refund from this operation makes Revoke transactions cheaper. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain for which the stake is being withdrawn. | -| owner | address | The address of the user who is withdrawing the stake. | - - -### setZeroVaultAddress - -```solidity -function setZeroVaultAddress(address zeroVault_) public -``` - - -Setter function for the `zeroVault` state variable. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| zeroVault_ | address | The address of the new Zero Vault - the wallet or contract to collect all the fees. | - - -### setPriceOracle - -```solidity -function setPriceOracle(address priceOracle_) public -``` - - -Setter function for the `priceOracle` state variable. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| priceOracle_ | address | The address of the new `ZNSPriceOracle` contract. | - - -### setStakingToken - -```solidity -function setStakingToken(address stakingToken_) public -``` - - -Setter function for the `stakingToken` state variable. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| stakingToken_ | address | The address of the new staking token (currently $ZERO). | - - -### setAccessController - -```solidity -function setAccessController(address accessController_) public -``` - - -Setter function for the `accessController` state variable. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController_ | address | The address of the new `ZNSAccessController` contract. | - - -### getAccessController - -```solidity -function getAccessController() external view returns (address) -``` - - -Getter function for the `accessController` state variable inherited from `AccessControlled`. - - - - -### _authorizeUpgrade - -```solidity -function _authorizeUpgrade(address newImplementation) internal view -``` - - -To use UUPS proxy we override this function and revert if `msg.sender` isn't authorized - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| newImplementation | address | The implementation contract to upgrade to | - - - diff --git a/docs/contracts/price/IZNSCurvePricer.md b/docs/contracts/price/IZNSCurvePricer.md index 05e8955f4..a0975bf81 100644 --- a/docs/contracts/price/IZNSCurvePricer.md +++ b/docs/contracts/price/IZNSCurvePricer.md @@ -153,7 +153,7 @@ function initialize(address accessController_, address registry_, struct ICurveP ### getPrice ```solidity -function getPrice(bytes32 parentHash, string label) external view returns (uint256) +function getPrice(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256) ``` @@ -161,6 +161,13 @@ function getPrice(bytes32 parentHash, string label) external view returns (uint2 `parentHash` param is here to allow pricer contracts to have different price configs for different subdomains +`skipValidityCheck` param is added to provide proper revert when the user is +calling this to find out the price of a domain that is not valid. But in Registrar contracts +we want to do this explicitly and before we get the price to have lower tx cost for reverted tx. +So Registrars will pass this bool as "true" to not repeat the validity check. +Note that if calling this function directly to find out the price, a user should always pass "false" +as `skipValidityCheck` param, otherwise, the price will be returned for an invalid label that is not +possible to register. @@ -180,7 +187,7 @@ Fees are only supported for PaymentType.STAKE ! ### getPriceAndFee ```solidity -function getPriceAndFee(bytes32 parentHash, string label) external view returns (uint256 price, uint256 stakeFee) +function getPriceAndFee(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256 price, uint256 stakeFee) ``` diff --git a/docs/contracts/price/IZNSFixedPricer.md b/docs/contracts/price/IZNSFixedPricer.md index 77f6066a8..8654774d4 100644 --- a/docs/contracts/price/IZNSFixedPricer.md +++ b/docs/contracts/price/IZNSFixedPricer.md @@ -62,21 +62,10 @@ Emitted when the `PriceConfig.feePercentage` is set in state for a specific `dom struct PriceConfig { uint256 price; uint256 feePercentage; + bool isSet; } ``` -### priceConfigs - -```solidity -function priceConfigs(bytes32 domainHash) external view returns (uint256 price, uint256 feePercentage) -``` - - - - - - - ### initialize ```solidity @@ -104,7 +93,7 @@ function setPrice(bytes32 domainHash, uint256 _price) external ### getPrice ```solidity -function getPrice(bytes32 parentHash, string label) external view returns (uint256) +function getPrice(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256) ``` @@ -112,6 +101,13 @@ function getPrice(bytes32 parentHash, string label) external view returns (uint2 `parentHash` param is here to allow pricer contracts to have different price configs for different subdomains +`skipValidityCheck` param is added to provide proper revert when the user is +calling this to find out the price of a domain that is not valid. But in Registrar contracts +we want to do this explicitly and before we get the price to have lower tx cost for reverted tx. +So Registrars will pass this bool as "true" to not repeat the validity check. +Note that if calling this function directly to find out the price, a user should always pass "false" +as `skipValidityCheck` param, otherwise, the price will be returned for an invalid label that is not +possible to register. @@ -143,7 +139,7 @@ Fees are only supported for PaymentType.STAKE ! ### getPriceAndFee ```solidity -function getPriceAndFee(bytes32 parentHash, string label) external view returns (uint256 price, uint256 fee) +function getPriceAndFee(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256 price, uint256 fee) ``` diff --git a/docs/contracts/price/ZNSCurvePricer.md b/docs/contracts/price/ZNSCurvePricer.md index 1e09ced9c..a7f0a7cdd 100644 --- a/docs/contracts/price/ZNSCurvePricer.md +++ b/docs/contracts/price/ZNSCurvePricer.md @@ -3,9 +3,9 @@ **Implementation of the Curve Pricing, module that calculates the price of a domain based on its length and the rules set by Zero ADMIN. -This module uses an asymptotic curve that starts from `maxPrice` and decreases in price -until it reaches `minPrice` at `maxLength` length of the domain name. Price after `maxLength` -is fixed and always equal to `minPrice`.** +This module uses an asymptotic curve that starts from `maxPrice` for all domains <= `baseLength`. +It then decreases in price, using the calculated price function below, until it reaches `minPrice` +at `maxLength` length of the domain name. Price after `maxLength` is fixed and always equal to `minPrice`.** @@ -38,6 +38,18 @@ Zero, for pricing root domains, uses this mapping as well under 0x0 hash. +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity @@ -65,12 +77,19 @@ Only Owner of the 0x0 hash (Zero owned address) can call this function. ### getPrice ```solidity -function getPrice(bytes32 parentHash, string label) public view returns (uint256) +function getPrice(bytes32 parentHash, string label, bool skipValidityCheck) public view returns (uint256) ``` Get the price of a given domain name +`skipValidityCheck` param is added to provide proper revert when the user is +calling this to find out the price of a domain that is not valid. But in Registrar contracts +we want to do this explicitly and before we get the price to have lower tx cost for reverted tx. +So Registrars will pass this bool as "true" to not repeat the validity check. +Note that if calling this function directly to find out the price, a user should always pass "false" +as `skipValidityCheck` param, otherwise, the price will be returned for an invalid label that is not +possible to register. #### Parameters @@ -78,6 +97,7 @@ Get the price of a given domain name | ---- | ---- | ----------- | | parentHash | bytes32 | The hash of the parent domain under which price is determined | | label | string | The label of the subdomain candidate to get the price for before/during registration | +| skipValidityCheck | bool | If true, skips the validity check for the label | ### getFeeForPrice @@ -103,7 +123,7 @@ based on the value set by the owner of the parent domain. ### getPriceAndFee ```solidity -function getPriceAndFee(bytes32 parentHash, string label) external view returns (uint256 price, uint256 stakeFee) +function getPriceAndFee(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256 price, uint256 stakeFee) ``` @@ -118,6 +138,7 @@ under the given parent. | ---- | ---- | ----------- | | parentHash | bytes32 | The hash of the parent domain under which price and fee are determined | | label | string | The label of the subdomain candidate to get the price and fee for before/during registration | +| skipValidityCheck | bool | | ### setPriceConfig @@ -132,6 +153,8 @@ Setter for `priceConfigs[domainHash]`. Only domain owner/operator can call this Validates the value of the `precisionMultiplier` and the whole config in order to avoid price spikes, fires `PriceConfigSet` event. Only ADMIN can call this function. +> This function should ALWAYS be used to set the config, since it's the only place where `isSet` is set to true. +> Use the other individual setters to modify only, since they do not set this variable! #### Parameters @@ -261,7 +284,7 @@ Only domain owner/operator can call this function. ### setFeePercentage ```solidity -function setFeePercentage(bytes32 domainHash, uint256 feePercentage) external +function setFeePercentage(bytes32 domainHash, uint256 feePercentage) public ``` @@ -302,10 +325,11 @@ function _getPrice(bytes32 parentHash, uint256 length) internal view returns (ui Internal function to calculate price based on the config set, and the length of the domain label. -Before we calculate the price, 3 different cases are possible: -1. `baseLength` is 0, which means we are returning `maxPrice` as a specific price for all domains -2. `length` is less than or equal to `baseLength`, which means a domain will cost `maxPrice` -3. `length` is greater than `maxLength`, which means a domain will cost `minPrice` +Before we calculate the price, 4 different cases are possible: +1. `maxPrice` is 0, which means all subdomains under this parent are free +2. `baseLength` is 0, which means we are returning `maxPrice` as a specific price for all domains +3. `length` is less than or equal to `baseLength`, which means a domain will cost `maxPrice` +4. `length` is greater than `maxLength`, which means a domain will cost `minPrice` The formula itself creates an asymptotic curve that decreases in pricing based on domain name length, base length and max price, the result is divided by the precision multiplier to remove numbers beyond diff --git a/docs/contracts/price/ZNSFixedPricer.md b/docs/contracts/price/ZNSFixedPricer.md index 9e044f302..4d1870f02 100644 --- a/docs/contracts/price/ZNSFixedPricer.md +++ b/docs/contracts/price/ZNSFixedPricer.md @@ -32,6 +32,18 @@ Mapping of domainHash to price config set by the domain owner/operator +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity @@ -65,12 +77,19 @@ Sets the price for a domain. Only callable by domain owner/operator. Emits a `Pr ### getPrice ```solidity -function getPrice(bytes32 parentHash, string label) public view returns (uint256) +function getPrice(bytes32 parentHash, string label, bool skipValidityCheck) public view returns (uint256) ``` Gets the price for a subdomain candidate label under the parent domain. +`skipValidityCheck` param is added to provide proper revert when the user is +calling this to find out the price of a domain that is not valid. But in Registrar contracts +we want to do this explicitly and before we get the price to have lower tx cost for reverted tx. +So Registrars will pass this bool as "true" to not repeat the validity check. +Note that if calling this function directly to find out the price, a user should always pass "false" +as `skipValidityCheck` param, otherwise, the price will be returned for an invalid label that is not +possible to register. #### Parameters @@ -78,6 +97,7 @@ Gets the price for a subdomain candidate label under the parent domain. | ---- | ---- | ----------- | | parentHash | bytes32 | The hash of the parent domain to check the price under | | label | string | The label of the subdomain candidate to check the price for | +| skipValidityCheck | bool | If true, skips the validity check for the label | ### setFeePercentage @@ -87,7 +107,8 @@ function setFeePercentage(bytes32 domainHash, uint256 feePercentage) public ``` -Sets the feePercentage for a domain. Only callable by domain owner/operator. Emits a `FeePercentageSet` event. +Sets the feePercentage for a domain. Only callable by domain owner/operator. +Emits a `FeePercentageSet` event. `feePercentage` is set as a part of the `PERCENTAGE_BASIS` of 10,000 where 1% = 100 @@ -110,6 +131,8 @@ Setter for `priceConfigs[domainHash]`. Only domain owner/operator can call this Sets both `PriceConfig.price` and `PriceConfig.feePercentage` in one call, fires `PriceSet` and `FeePercentageSet` events. +> This function should ALWAYS be used to set the config, since it's the only place where `isSet` is set to true. +> Use the other individual setters to modify only, since they do not set this variable! #### Parameters @@ -142,7 +165,7 @@ based on the value set by the owner of the parent domain. ### getPriceAndFee ```solidity -function getPriceAndFee(bytes32 parentHash, string label) external view returns (uint256 price, uint256 fee) +function getPriceAndFee(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256 price, uint256 fee) ``` @@ -157,6 +180,7 @@ under the given parent. | ---- | ---- | ----------- | | parentHash | bytes32 | The hash of the parent domain under which price and fee are determined | | label | string | The label of the subdomain candidate to get the price and fee for before/during registration | +| skipValidityCheck | bool | If true, skips the validity check for the label | ### setRegistry @@ -172,6 +196,42 @@ This function is required for all contracts inheriting `ARegistryWired`. +### _setPrice + +```solidity +function _setPrice(bytes32 domainHash, uint256 price) internal +``` + + +Internal function for set price + + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| domainHash | bytes32 | The hash of the domain | +| price | uint256 | The new price | + + +### _setFeePercentage + +```solidity +function _setFeePercentage(bytes32 domainHash, uint256 feePercentage) internal +``` + + +Internal function for setFeePercentage + + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| domainHash | bytes32 | The hash of the domain | +| feePercentage | uint256 | The new feePercentage | + + ### _authorizeUpgrade ```solidity diff --git a/docs/contracts/registrar/IZNSSubRegistrar.md b/docs/contracts/registrar/IZNSSubRegistrar.md index 68e175f22..7610f3cf1 100644 --- a/docs/contracts/registrar/IZNSSubRegistrar.md +++ b/docs/contracts/registrar/IZNSSubRegistrar.md @@ -68,6 +68,18 @@ Emitted when a `mintlist` is updated for a domain. +### MintlistCleared + +```solidity +event MintlistCleared(bytes32 domainHash) +``` + + + + + + + ### RootRegistrarSet ```solidity @@ -92,10 +104,10 @@ function distrConfigs(bytes32 domainHash) external view returns (contract IZNSPr -### mintlist +### isMintlistedForDomain ```solidity -function mintlist(bytes32 domainHash, address candidate) external view returns (bool) +function isMintlistedForDomain(bytes32 domainHash, address candidate) external view returns (bool) ``` @@ -200,6 +212,30 @@ function updateMintlistForDomain(bytes32 domainHash, address[] candidates, bool[ +### clearMintlistForDomain + +```solidity +function clearMintlistForDomain(bytes32 domainHash) external +``` + + + + + + + +### clearMintlistAndLock + +```solidity +function clearMintlistAndLock(bytes32 domainHash) external +``` + + + + + + + ### setRegistry ```solidity diff --git a/docs/contracts/registrar/ZNSRootRegistrar.md b/docs/contracts/registrar/ZNSRootRegistrar.md index fe22797cf..46d462a78 100644 --- a/docs/contracts/registrar/ZNSRootRegistrar.md +++ b/docs/contracts/registrar/ZNSRootRegistrar.md @@ -77,6 +77,18 @@ contract IZNSSubRegistrar subRegistrar +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity @@ -370,18 +382,6 @@ Only ADMIN in `ZNSAccessController` can call this function. | addressResolver_ | address | Address of the `ZNSAddressResolver` contract | -### _isValidString - -```solidity -function _isValidString(string str) internal pure returns (bool) -``` - - - - - - - ### _authorizeUpgrade ```solidity diff --git a/docs/contracts/registrar/ZNSSubRegistrar.md b/docs/contracts/registrar/ZNSSubRegistrar.md index 9adbd15c9..1bd11eccc 100644 --- a/docs/contracts/registrar/ZNSSubRegistrar.md +++ b/docs/contracts/registrar/ZNSSubRegistrar.md @@ -37,10 +37,26 @@ Note that the rules outlined in the DistributionConfig are only applied to direc +### Mintlist + + + + + + + + +```solidity +struct Mintlist { + mapping(uint256 => mapping(address => bool)) list; + uint256 ownerIndex; +} +``` + ### mintlist ```solidity -mapping(bytes32 => mapping(address => bool)) mintlist +mapping(bytes32 => struct ZNSSubRegistrar.Mintlist) mintlist ``` @@ -63,6 +79,18 @@ modifier onlyOwnerOperatorOrRegistrar(bytes32 domainHash) +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity @@ -119,7 +147,8 @@ function setDistributionConfigForDomain(bytes32 domainHash, struct IDistribution ``` -Setter for `distrConfigs[domainHash]`. Only domain owner/operator or ZNSRootRegistrar can call this function. +Setter for `distrConfigs[domainHash]`. +Only domain owner/operator or ZNSRootRegistrar can call this function. This config can be changed by the domain owner/operator at any time or be set after registration if the config was not provided during the registration. @@ -175,24 +204,10 @@ Fires `PaymentTypeSet` event. | paymentType | enum IDistributionConfig.PaymentType | The new payment type to set | -### _setAccessTypeForDomain - -```solidity -function _setAccessTypeForDomain(bytes32 domainHash, enum IDistributionConfig.AccessType accessType) internal -``` - - - - -Internal function used by this contract to set the access type for a subdomain -during revocation process. - - - ### setAccessTypeForDomain ```solidity -function setAccessTypeForDomain(bytes32 domainHash, enum IDistributionConfig.AccessType accessType) external +function setAccessTypeForDomain(bytes32 domainHash, enum IDistributionConfig.AccessType accessType) public ``` @@ -233,6 +248,42 @@ Fires `MintlistUpdated` event. | allowed | bool[] | The array of booleans indicating whether to add or remove the candidate | +### isMintlistedForDomain + +```solidity +function isMintlistedForDomain(bytes32 domainHash, address candidate) external view returns (bool) +``` + + + + + + + +### clearMintlistForDomain + +```solidity +function clearMintlistForDomain(bytes32 domainHash) public +``` + + + + + + + +### clearMintlistAndLock + +```solidity +function clearMintlistAndLock(bytes32 domainHash) external +``` + + + + + + + ### setRegistry ```solidity diff --git a/docs/contracts/registry/IZNSRegistry.md b/docs/contracts/registry/IZNSRegistry.md index b848b249f..7e0e93ca4 100644 --- a/docs/contracts/registry/IZNSRegistry.md +++ b/docs/contracts/registry/IZNSRegistry.md @@ -108,14 +108,9 @@ function initialize(address accessController) external ``` -Create an instance of the ZNSRegistry contract -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController | address | The addrss of the access controller | ### exists @@ -125,14 +120,9 @@ function exists(bytes32 domainHash) external view returns (bool) ``` -Check if a given domain exists -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of a domain's name | ### isOwnerOrOperator @@ -142,15 +132,9 @@ function isOwnerOrOperator(bytes32 domainHash, address candidate) external view ``` -Checks if provided address is an owner or an operator of the provided domain -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of a domain's name | -| candidate | address | The address for which we are checking access | ### isOperatorFor @@ -191,14 +175,9 @@ function getDomainRecord(bytes32 domainHash) external view returns (struct IZNSR ``` -Get a record for a domain -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | the hash of a domain's name | ### getDomainOwner @@ -208,14 +187,9 @@ function getDomainOwner(bytes32 domainHash) external view returns (address) ``` -Get the owner of the given domain -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | the hash of a domain's name | ### getDomainResolver @@ -225,14 +199,9 @@ function getDomainResolver(bytes32 domainHash) external view returns (address) ``` -Get the default resolver for the given domain -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of a domain's name | ### createDomainRecord @@ -242,16 +211,9 @@ function createDomainRecord(bytes32 domainHash, address owner, address resolver) ``` -Create a new domain record -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain name | -| owner | address | The owner of the new domain | -| resolver | address | The resolver of the new domain | ### updateDomainRecord @@ -261,16 +223,9 @@ function updateDomainRecord(bytes32 domainHash, address owner, address resolver) ``` -Update an existing domain record's owner or resolver -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain | -| owner | address | The owner or an allowed operator of that domain | -| resolver | address | The resolver for the domain | ### updateDomainOwner @@ -280,15 +235,9 @@ function updateDomainOwner(bytes32 domainHash, address owner) external ``` -Update a domain's owner -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | the hash of a domain's name | -| owner | address | The account to transfer ownership to | ### updateDomainResolver @@ -298,15 +247,9 @@ function updateDomainResolver(bytes32 domainHash, address resolver) external ``` -Update the domain's default resolver -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | the hash of a domain's name | -| resolver | address | The new default resolver | ### deleteRecord @@ -316,14 +259,9 @@ function deleteRecord(bytes32 domainHash) external ``` -Delete a domain's record -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain name | diff --git a/docs/contracts/registry/ZNSRegistry.md b/docs/contracts/registry/ZNSRegistry.md index a8df2f79e..efcbe46f1 100644 --- a/docs/contracts/registry/ZNSRegistry.md +++ b/docs/contracts/registry/ZNSRegistry.md @@ -65,6 +65,23 @@ modifier onlyOwner(bytes32 domainHash) Revert if `msg.sender` is not the owner. Used for owner restricted functions. +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| domainHash | bytes32 | the hash of a domain's name | + + +### constructor + +```solidity +constructor() public +``` + + + + + ### initialize @@ -76,7 +93,7 @@ function initialize(address accessController_) external Initializer for the `ZNSRegistry` proxy. -! The owner of the 0x0 hash should be a multisig ! +! The owner of the 0x0 hash should be a multisig ideally, but EOA can be used to deploy ! > Admin account deploying the contract will be the owner of the 0x0 hash ! #### Parameters diff --git a/docs/contracts/resolver/IZNSAddressResolver.md b/docs/contracts/resolver/IZNSAddressResolver.md index fbbdb3731..ed5703144 100644 --- a/docs/contracts/resolver/IZNSAddressResolver.md +++ b/docs/contracts/resolver/IZNSAddressResolver.md @@ -35,14 +35,7 @@ function supportsInterface(bytes4 interfaceId) external view returns (bool) -ERC-165 check for implementation identifier -Supports interfaces IZNSAddressResolver and IERC165 -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| interfaceId | bytes4 | ID to check, XOR of the first 4 bytes of each function signature | ### getAddress @@ -54,13 +47,7 @@ function getAddress(bytes32 domainHash) external view returns (address) -Resolves address given domain name hash -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The identifying hash of a domain's name | ### setAddress @@ -72,14 +59,7 @@ function setAddress(bytes32 domainHash, address newAddress) external -Sets the address of a domain name hash, only registry -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The identifying hash of a domain's name | -| newAddress | address | The new domain owner | ### getInterfaceId @@ -113,15 +93,9 @@ function initialize(address _accessController, address _registry) external ``` -Initialize an instance of the ZNSAddressResolver -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| _accessController | address | The access controller | -| _registry | address | The registry address | diff --git a/docs/contracts/resolver/ZNSAddressResolver.md b/docs/contracts/resolver/ZNSAddressResolver.md index 26da07001..9abe50cfa 100644 --- a/docs/contracts/resolver/ZNSAddressResolver.md +++ b/docs/contracts/resolver/ZNSAddressResolver.md @@ -22,6 +22,18 @@ to Ethereum wallets or contracts registered in ZNS. +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity diff --git a/docs/contracts/token/ZNSDomainToken.md b/docs/contracts/token/ZNSDomainToken.md index f166d712f..a40bbcf2c 100644 --- a/docs/contracts/token/ZNSDomainToken.md +++ b/docs/contracts/token/ZNSDomainToken.md @@ -11,6 +11,18 @@ the `ZNSRootRegistrar.sol` contract or any address holding a REGISTRAR_ROLE. +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity @@ -175,9 +187,15 @@ function supportsInterface(bytes4 interfaceId) public view virtual returns (bool ``` +To allow for user extension of the protocol we have to +enable checking acceptance of new interfaces to ensure they are supported +#### Parameters +| Name | Type | Description | +| ---- | ---- | ----------- | +| interfaceId | bytes4 | The interface ID | ### _burn @@ -187,9 +205,14 @@ function _burn(uint256 tokenId) internal ``` +ERC721 `_burn` function +#### Parameters +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | uint256 | The ID of the token to burn | ### _baseURI @@ -199,12 +222,9 @@ function _baseURI() internal view returns (string) ``` +Return the baseURI -Base URI for computing {tokenURI}. If set, the resulting URI for each -token will be the concatenation of the `baseURI` and the `tokenId`. Empty -by default, can be overridden in child contracts. - ### _authorizeUpgrade diff --git a/docs/contracts/treasury/ZNSTreasury.md b/docs/contracts/treasury/ZNSTreasury.md index aecee6583..9a7bf5093 100644 --- a/docs/contracts/treasury/ZNSTreasury.md +++ b/docs/contracts/treasury/ZNSTreasury.md @@ -33,16 +33,28 @@ mapping(bytes32 => struct IZNSTreasury.Stake) stakedForDomain ``` -The mapping that stores `Stake` struct mapped by domainHash. It stores the staking data for each domain in zNS. -Note that there is no owner address to which the stake is tied to. Instead, the owner data from `ZNSRegistry` -is used to identify a user who owns the stake. So the staking data is tied to the owner of the Name. -This should be taken into account, since any transfer of the Token to another address, -and the system, allowing them to Reclaim the Name, will also allow them to withdraw the stake. +The mapping that stores `Stake` struct mapped by domainHash. It stores the staking data for +each domain in zNS. Note that there is no owner address to which the stake is tied to. Instead, the +owner data from `ZNSRegistry` is used to identify a user who owns the stake. So the staking data is +tied to the owner of the Name. This should be taken into account, since any transfer of the Token to +another address, and the system, allowing them to Reclaim the Name, will also allow them to withdraw the stake. > Stake is owned by the owner of the Name in `ZNSRegistry` which the owner of the Token can reclaim! +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity @@ -131,8 +143,8 @@ An alternative to `stakeForDomain()` for cases when a parent domain is using Pay Note that `stakeFee` transfers are NOT present here, since a fee on top of the price is ONLY supported for STAKE payment type. This function is called by `ZNSRootRegistrar.sol` when a user wants to register a domain. -This function uses a different approach than `stakeForDomain()` as it performs 2 transfers from the user's wallet. -Is uses `paymentConfigs[parentHash]` to get the token and beneficiary for the parent domain. +This function uses a different approach than `stakeForDomain()` as it performs 2 transfers from the user's +wallet. Is uses `paymentConfigs[parentHash]` to get the token and beneficiary for the parent domain. Can be called ONLY by the REGISTRAR_ROLE. Fires a `DirectPaymentProcessed` event. #### Parameters @@ -216,6 +228,30 @@ This function is required for all contracts inheriting `ARegistryWired`. +### _setBeneficiary + +```solidity +function _setBeneficiary(bytes32 domainHash, address beneficiary) internal +``` + + + + + + + +### _setPaymentToken + +```solidity +function _setPaymentToken(bytes32 domainHash, address paymentToken) internal +``` + + + + + + + ### _authorizeUpgrade ```solidity diff --git a/docs/contracts/types/ICurvePriceConfig.md b/docs/contracts/types/ICurvePriceConfig.md index 3e5636290..4f7a31a62 100644 --- a/docs/contracts/types/ICurvePriceConfig.md +++ b/docs/contracts/types/ICurvePriceConfig.md @@ -34,6 +34,7 @@ struct CurvePriceConfig { uint256 baseLength; uint256 precisionMultiplier; uint256 feePercentage; + bool isSet; } ``` diff --git a/docs/contracts/types/IDistributionConfig.md b/docs/contracts/types/IDistributionConfig.md index 42d157100..9c9208467 100644 --- a/docs/contracts/types/IDistributionConfig.md +++ b/docs/contracts/types/IDistributionConfig.md @@ -1,7 +1,8 @@ ## IDistributionConfig -**IDistributionConfig.sol - An interface containing all types required for distribution configuration of a domain.** +**IDistributionConfig.sol - An interface containing all types required for +distribution configuration of a domain.** @@ -9,7 +10,8 @@ Types outlined in this config are stored on the `ZNSSubRegistrar` contract and a how subdomains are distributed for each parent domain. Below are docs for the types in this file: - `DistributionConfig`: Struct containing the configuration data for a parent domain: - + `pricerContract`: The address of the pricer contract chosen by the owner of the parent domain (IZNSPricer type required!) + + `pricerContract`: The address of the pricer contract chosen by the owner of the + parent domain (IZNSPricer type required!) + `paymentType`: The payment type chosen by the owner of the parent domain + `accessType`: The access type chosen by the owner of the parent domain - `AccessType`: Enum signifying the access type of a parent domain: diff --git a/docs/contracts/types/IZNSPricer.md b/docs/contracts/types/IZNSPricer.md index 945280222..3f57a8567 100644 --- a/docs/contracts/types/IZNSPricer.md +++ b/docs/contracts/types/IZNSPricer.md @@ -11,7 +11,7 @@ Base interface required to be inherited by all Pricing contracts to work with zN ### getPrice ```solidity -function getPrice(bytes32 parentHash, string label) external view returns (uint256) +function getPrice(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256) ``` @@ -19,13 +19,20 @@ function getPrice(bytes32 parentHash, string label) external view returns (uint2 `parentHash` param is here to allow pricer contracts to have different price configs for different subdomains +`skipValidityCheck` param is added to provide proper revert when the user is +calling this to find out the price of a domain that is not valid. But in Registrar contracts +we want to do this explicitly and before we get the price to have lower tx cost for reverted tx. +So Registrars will pass this bool as "true" to not repeat the validity check. +Note that if calling this function directly to find out the price, a user should always pass "false" +as `skipValidityCheck` param, otherwise, the price will be returned for an invalid label that is not +possible to register. ### getPriceAndFee ```solidity -function getPriceAndFee(bytes32 parentHash, string label) external view returns (uint256 price, uint256 fee) +function getPriceAndFee(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256 price, uint256 fee) ``` From b88e44085366be12d7121a3ee71ac5b2ad474a79 Mon Sep 17 00:00:00 2001 From: James Earle Date: Thu, 2 Nov 2023 12:11:27 -0700 Subject: [PATCH 2/2] regenerate documentation --- docs/contracts/access/AccessControlled.md | 94 ----- .../contracts/distribution/IZNSPriceOracle.md | 306 --------------- docs/contracts/distribution/IZNSRegistrar.md | 260 ------------- docs/contracts/distribution/IZNSTreasury.md | 197 ---------- docs/contracts/distribution/ZNSPriceOracle.md | 354 ------------------ docs/contracts/distribution/ZNSRegistrar.md | 329 ---------------- docs/contracts/distribution/ZNSTreasury.md | 256 ------------- docs/contracts/price/IZNSCurvePricer.md | 11 +- docs/contracts/price/IZNSFixedPricer.md | 24 +- docs/contracts/price/ZNSCurvePricer.md | 44 ++- docs/contracts/price/ZNSFixedPricer.md | 66 +++- docs/contracts/registrar/IZNSSubRegistrar.md | 40 +- docs/contracts/registrar/ZNSRootRegistrar.md | 24 +- docs/contracts/registrar/ZNSSubRegistrar.md | 85 ++++- docs/contracts/registry/IZNSRegistry.md | 62 --- docs/contracts/registry/ZNSRegistry.md | 19 +- .../contracts/resolver/IZNSAddressResolver.md | 26 -- docs/contracts/resolver/ZNSAddressResolver.md | 12 + docs/contracts/token/ZNSDomainToken.md | 28 +- docs/contracts/treasury/ZNSTreasury.md | 50 ++- docs/contracts/types/ICurvePriceConfig.md | 1 + docs/contracts/types/IDistributionConfig.md | 6 +- docs/contracts/types/IZNSPricer.md | 11 +- 23 files changed, 345 insertions(+), 1960 deletions(-) delete mode 100644 docs/contracts/access/AccessControlled.md delete mode 100644 docs/contracts/distribution/IZNSPriceOracle.md delete mode 100644 docs/contracts/distribution/IZNSRegistrar.md delete mode 100644 docs/contracts/distribution/IZNSTreasury.md delete mode 100644 docs/contracts/distribution/ZNSPriceOracle.md delete mode 100644 docs/contracts/distribution/ZNSRegistrar.md delete mode 100644 docs/contracts/distribution/ZNSTreasury.md diff --git a/docs/contracts/access/AccessControlled.md b/docs/contracts/access/AccessControlled.md deleted file mode 100644 index 8bd578960..000000000 --- a/docs/contracts/access/AccessControlled.md +++ /dev/null @@ -1,94 +0,0 @@ -## AccessControlled - - -**This abstract contract outlines basic functionality, declares functions -that need to be implemented to provide a deterministic connection to `ZNSAccessController` module.** - - - -In order to connect an arbitrary module to `ZNSAccessController` and it's functionality, -this contract needs to be inherited by the module. - - - -### AccessControllerSet - -```solidity -event AccessControllerSet(address accessController) -``` - - -Emitted when the access controller contract address is set. - - - - -### accessController - -```solidity -contract IZNSAccessController accessController -``` - - -Address of the ZNSAccessController contract. - - - - -### onlyAdmin - -```solidity -modifier onlyAdmin() -``` - - -Modifier to make a function callable only when caller is an admin. -Implemented here to avoid declaring this in every single contract that uses it. - - - - -### getAccessController - -```solidity -function getAccessController() external view virtual returns (address) -``` - - -Virtual function to make sure the getter is always implemented in children, -otherwise we will not be able to read the AC address in children - - - - -### setAccessController - -```solidity -function setAccessController(address _accessController) external virtual -``` - - -Virtual function to make sure the setter is always implemented in children, -otherwise we will not be able to reset the AC address in children - - - - -### _setAccessController - -```solidity -function _setAccessController(address _accessController) internal -``` - - -Internal function to set the access controller address. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _accessController | address | Address of the ZNSAccessController contract. | - - - diff --git a/docs/contracts/distribution/IZNSPriceOracle.md b/docs/contracts/distribution/IZNSPriceOracle.md deleted file mode 100644 index 29f33335c..000000000 --- a/docs/contracts/distribution/IZNSPriceOracle.md +++ /dev/null @@ -1,306 +0,0 @@ -## IZNSPriceOracle - - - - - -**`DomainPriceConfig` struct properties:** - -- `maxPrice` (uint256): Maximum price for a domain returned at <= `baseLength` -- `minPrice` (uint256): Minimum price for a domain returned at > `maxLength` -- `maxLength` (uint256): Maximum length of a domain name. If the name is longer than this value we return the `minPrice` -- `baseLength` (uint256): Base length of a domain name. If the name is less than or equal to this value we return the `maxPrice` -- `precisionMultiplier` (uint256): The precision multiplier of the price. This multiplier -should be picked based on the number of token decimals to calculate properly. -e.g. if we use a token with 18 decimals, and want precision of 2, -our precision multiplier will be equal 10^18 - 10^2 = 10^16 - - - -### MaxPriceSet - -```solidity -event MaxPriceSet(uint256 price) -``` - - -Emitted when the `maxPrice` is set in `rootDomainPriceConfig` - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| price | uint256 | The new maxPrice value | - - -### MinPriceSet - -```solidity -event MinPriceSet(uint256 price) -``` - - -Emitted when the `minPrice` is set in `rootDomainPriceConfig` - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| price | uint256 | The new minPrice value | - - -### BaseLengthSet - -```solidity -event BaseLengthSet(uint256 length) -``` - - -Emitted when the `baseLength` is set in `rootDomainPriceConfig` - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| length | uint256 | The new baseLength value | - - -### MaxLengthSet - -```solidity -event MaxLengthSet(uint256 length) -``` - - -Emitted when the `maxLength` is set in `rootDomainPriceConfig` - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| length | uint256 | The new maxLength value | - - -### PrecisionMultiplierSet - -```solidity -event PrecisionMultiplierSet(uint256 precision) -``` - - -Emitted when the `precisionMultiplier` is set in `rootDomainPriceConfig` - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| precision | uint256 | The new precisionMultiplier value | - - -### FeePercentageSet - -```solidity -event FeePercentageSet(uint256 feePercentage) -``` - - -Emitted when the `feePercentage` is set in state - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| feePercentage | uint256 | The new feePercentage value | - - -### PriceConfigSet - -```solidity -event PriceConfigSet(uint256 maxPrice, uint256 minPrice, uint256 maxLength, uint256 baseLength, uint256 precisionMultiplier) -``` - - -Emitted when the full `rootDomainPriceConfig` is set in state - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maxPrice | uint256 | The new `maxPrice` value | -| minPrice | uint256 | The new `minPrice` value | -| maxLength | uint256 | The new `maxLength` value | -| baseLength | uint256 | The new `baseLength` value | -| precisionMultiplier | uint256 | The new `precisionMultiplier` value | - - -### DomainPriceConfig - - - - - - - - -```solidity -struct DomainPriceConfig { - uint256 maxPrice; - uint256 minPrice; - uint256 maxLength; - uint256 baseLength; - uint256 precisionMultiplier; -} -``` - -### initialize - -```solidity -function initialize(address accessController_, struct IZNSPriceOracle.DomainPriceConfig priceConfig_, uint256 regFeePercentage_) external -``` - - - - - - - -### getPrice - -```solidity -function getPrice(string name) external view returns (uint256 totalPrice, uint256 domainPrice, uint256 fee) -``` - - - - - - - -### getRegistrationFee - -```solidity -function getRegistrationFee(uint256 domainPrice) external view returns (uint256) -``` - - - - - - - -### setPriceConfig - -```solidity -function setPriceConfig(struct IZNSPriceOracle.DomainPriceConfig priceConfig) external -``` - - - - - - - -### setMaxPrice - -```solidity -function setMaxPrice(uint256 maxPrice) external -``` - - - - - - - -### setMinPrice - -```solidity -function setMinPrice(uint256 minPrice) external -``` - - - - - - - -### setBaseLength - -```solidity -function setBaseLength(uint256 length) external -``` - - - - - - - -### setMaxLength - -```solidity -function setMaxLength(uint256 length) external -``` - - - - - - - -### setPrecisionMultiplier - -```solidity -function setPrecisionMultiplier(uint256 multiplier) external -``` - - - - - - - -### setRegistrationFeePercentage - -```solidity -function setRegistrationFeePercentage(uint256 regFeePercentage) external -``` - - - - - - - -### setAccessController - -```solidity -function setAccessController(address accessController) external -``` - - - - - - - -### getAccessController - -```solidity -function getAccessController() external view returns (address) -``` - - - - - - - - diff --git a/docs/contracts/distribution/IZNSRegistrar.md b/docs/contracts/distribution/IZNSRegistrar.md deleted file mode 100644 index bc718d181..000000000 --- a/docs/contracts/distribution/IZNSRegistrar.md +++ /dev/null @@ -1,260 +0,0 @@ -## IZNSRegistrar - - - - - - - - -### DomainRegistered - -```solidity -event DomainRegistered(bytes32 domainHash, uint256 tokenId, string name, address registrant, address resolver, address domainAddress) -``` - - -Emitted when a NEW domain is registered. - -`domainAddress` parameter is the address to which a domain name will relate to in ZNS. -E.g. if a user made a domain for his wallet, the address of the wallet will be the `domainAddress`. -This can be 0 as this variable is not required to perform registration process -and can be set at a later time by the domain owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain registered | -| tokenId | uint256 | The tokenId of the domain registered | -| name | string | The name as string of the domain registered | -| registrant | address | The address that called `ZNSRegistrar.registerDomain()` | -| resolver | address | The resolver contract address of the domain registered | -| domainAddress | address | The domain address of the domain registered | - - -### DomainRevoked - -```solidity -event DomainRevoked(bytes32 domainHash, address registrant) -``` - - -Emitted when a domain is revoked. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain revoked | -| registrant | address | The address that called `ZNSRegistrar.revokeDomain()` | - - -### DomainReclaimed - -```solidity -event DomainReclaimed(bytes32 domainHash, address registrant) -``` - - -Emitted when an ownership of the Name is reclaimed by the Token owner. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain reclaimed | -| registrant | address | The address that called `ZNSRegistrar.reclaimDomain()` | - - -### RegistrySet - -```solidity -event RegistrySet(address registry) -``` - - -Emitted when the `registry` address is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| registry | address | The new address of the registry contract | - - -### TreasurySet - -```solidity -event TreasurySet(address treasury) -``` - - -Emitted when the `treasury` address is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| treasury | address | The new address of the treasury contract | - - -### DomainTokenSet - -```solidity -event DomainTokenSet(address domainToken) -``` - - -Emitted when the `domainToken` address is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainToken | address | The new address of the domainToken contract | - - -### AddressResolverSet - -```solidity -event AddressResolverSet(address addressResolver) -``` - - -Emitted when the `addressResolver` address is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| addressResolver | address | The new address of the addressResolver contract | - - -### registerDomain - -```solidity -function registerDomain(string name, address resolverContent) external returns (bytes32) -``` - - - - - - - -### revokeDomain - -```solidity -function revokeDomain(bytes32 domainHash) external -``` - - - - - - - -### reclaimDomain - -```solidity -function reclaimDomain(bytes32 domainHash) external -``` - - - - - - - -### setRegistry - -```solidity -function setRegistry(address registry_) external -``` - - - - - - - -### setTreasury - -```solidity -function setTreasury(address treasury_) external -``` - - - - - - - -### setDomainToken - -```solidity -function setDomainToken(address domainToken_) external -``` - - - - - - - -### setAddressResolver - -```solidity -function setAddressResolver(address addressResolver_) external -``` - - - - - - - -### setAccessController - -```solidity -function setAccessController(address accessController_) external -``` - - - - - - - -### getAccessController - -```solidity -function getAccessController() external view returns (address) -``` - - - - - - - -### initialize - -```solidity -function initialize(address accessController_, address registry_, address treasury_, address domainToken_, address addressResolver_) external -``` - - - - - - - - diff --git a/docs/contracts/distribution/IZNSTreasury.md b/docs/contracts/distribution/IZNSTreasury.md deleted file mode 100644 index f4c341d83..000000000 --- a/docs/contracts/distribution/IZNSTreasury.md +++ /dev/null @@ -1,197 +0,0 @@ -## IZNSTreasury - - - - - - - - -### StakeDeposited - -```solidity -event StakeDeposited(bytes32 domainHash, string domainName, address depositor, uint256 stakeAmount, uint256 registrationFee) -``` - - -Emitted when a new stake is deposited upon registration of a new domain. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain name | -| domainName | string | The domain name as a string | -| depositor | address | The address of the depositing user / new domain owner | -| stakeAmount | uint256 | The amount they are depositing / price of the domain based on name length | -| registrationFee | uint256 | The registration fee paid by the user on top of the staked amount | - - -### StakeWithdrawn - -```solidity -event StakeWithdrawn(bytes32 domainHash, address owner, uint256 stakeAmount) -``` - - -Emitted when a stake is withdrawn upon domain revocation. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain name being revoked | -| owner | address | The owner of the domain being revoked | -| stakeAmount | uint256 | The staked amount withdrawn to the user after revoking | - - -### PriceOracleSet - -```solidity -event PriceOracleSet(address priceOracle) -``` - - -Emitted when `priceOracle` is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| priceOracle | address | The new address of the price oracle contract | - - -### StakingTokenSet - -```solidity -event StakingTokenSet(address stakingToken) -``` - - -Emitted when `stakingToken` is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| stakingToken | address | The new address of the ERC-20 compliant staking token contract | - - -### ZeroVaultAddressSet - -```solidity -event ZeroVaultAddressSet(address zeroVault) -``` - - -Emitted when `zeroVault` is set in state. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| zeroVault | address | The new address of the zero vault contract or wallet | - - -### stakeForDomain - -```solidity -function stakeForDomain(bytes32 domainHash, string domainName, address depositor) external -``` - - - - - - - -### unstakeForDomain - -```solidity -function unstakeForDomain(bytes32 domainHash, address owner) external -``` - - - - - - - -### setZeroVaultAddress - -```solidity -function setZeroVaultAddress(address zeroVaultAddress) external -``` - - - - - - - -### setPriceOracle - -```solidity -function setPriceOracle(address priceOracle_) external -``` - - - - - - - -### setStakingToken - -```solidity -function setStakingToken(address stakingToken_) external -``` - - - - - - - -### setAccessController - -```solidity -function setAccessController(address accessController) external -``` - - - - - - - -### getAccessController - -```solidity -function getAccessController() external view returns (address) -``` - - - - - - - -### initialize - -```solidity -function initialize(address accessController_, address priceOracle_, address stakingToken_, address zeroVault_) external -``` - - - - - - - - diff --git a/docs/contracts/distribution/ZNSPriceOracle.md b/docs/contracts/distribution/ZNSPriceOracle.md deleted file mode 100644 index 16c83250f..000000000 --- a/docs/contracts/distribution/ZNSPriceOracle.md +++ /dev/null @@ -1,354 +0,0 @@ -## ZNSPriceOracle - - -**Implementation of the Price Oracle, module that calculates the price of a domain -based on its length and the rules set by Zero ADMIN.** - - - - - - -### PERCENTAGE_BASIS - -```solidity -uint256 PERCENTAGE_BASIS -``` - - -Value used as a basis for percentage calculations, -since Solidity does not support fractions. - - - - -### rootDomainPriceConfig - -```solidity -struct IZNSPriceOracle.DomainPriceConfig rootDomainPriceConfig -``` - - -Struct for each configurable price variable -that participates in the price calculation. - -See [IZNSPriceOracle.md](./IZNSPriceOracle.md) for more details. - - - -### feePercentage - -```solidity -uint256 feePercentage -``` - - -The registration fee value in percentage as basis points (parts per 10,000) - so the 2% value would be represented as 200. - See [getRegistrationFee](#getregistrationfee) for the actual fee calc process. - - - - -### initialize - -```solidity -function initialize(address accessController_, struct IZNSPriceOracle.DomainPriceConfig priceConfig_, uint256 regFeePercentage_) public -``` - - -Proxy initializer to set the initial state of the contract after deployment. -Only ADMIN can call this function. - -> Note the for DomainPriceConfig we set each value individually and calling -2 important functions that validate all of the config's values against the formula: -- `setPrecisionMultiplier()` to validate precision multiplier -- `_validateConfig()` to validate the whole config in order to avoid price spikes - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController_ | address | the address of the ZNSAccessController contract. | -| priceConfig_ | struct IZNSPriceOracle.DomainPriceConfig | a number of variables that participate in the price calculation. | -| regFeePercentage_ | uint256 | the registration fee value in percentage as basis points (parts per 10,000) | - - -### getPrice - -```solidity -function getPrice(string name) external view returns (uint256 totalPrice, uint256 domainPrice, uint256 fee) -``` - - -Get the price of a given domain name - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| name | string | The name of the domain to check | - - -### getRegistrationFee - -```solidity -function getRegistrationFee(uint256 domainPrice) public view returns (uint256) -``` - - -Get the registration fee amount in `stakingToken` for a specific domain price -as `domainPrice * feePercentage / PERCENTAGE_BASIS`. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainPrice | uint256 | The price of the domain | - - -### setPriceConfig - -```solidity -function setPriceConfig(struct IZNSPriceOracle.DomainPriceConfig priceConfig) external -``` - - -Setter for `rootDomainPriceConfig`. Only ADMIN can call this function. - -Validates the value of the `precisionMultiplier` and the whole config in order to avoid price spikes, -fires `PriceConfigSet` event. -Only ADMIN can call this function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| priceConfig | struct IZNSPriceOracle.DomainPriceConfig | The new price config to set | - - -### setMaxPrice - -```solidity -function setMaxPrice(uint256 maxPrice) external -``` - - -Sets the max price for domains. Validates the config with the new price. -Fires `MaxPriceSet` event. -Only ADMIN can call this function. -> `maxPrice` can be set to 0 to make all domains free! - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maxPrice | uint256 | The maximum price to set in $ZERO | - - -### setMinPrice - -```solidity -function setMinPrice(uint256 minPrice) external -``` - - -Sets the minimum price for domains. Validates the config with the new price. -Fires `MinPriceSet` event. -Only ADMIN can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| minPrice | uint256 | The minimum price to set in $ZERO | - - -### setBaseLength - -```solidity -function setBaseLength(uint256 length) external -``` - - -Set the value of the domain name length boundary where the `maxPrice` applies -e.g. A value of '5' means all domains <= 5 in length cost the `maxPrice` price -Validates the config with the new length. Fires `BaseLengthSet` event. -Only ADMIN can call this function. -> `baseLength` can be set to 0 to make all domains cost `maxPrice`! -> This indicates to the system that we are -> currently in a special phase where we define an exact price for all domains -> e.g. promotions or sales - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| length | uint256 | Boundary to set | - - -### setMaxLength - -```solidity -function setMaxLength(uint256 length) external -``` - - -Set the maximum length of a domain name to which price formula applies. -All domain names (labels) that are longer than this value will cost the fixed price of `minPrice`, -and the pricing formula will not apply to them. -Validates the config with the new length. -Fires `MaxLengthSet` event. -Only ADMIN can call this function. -> `maxLength` can be set to 0 to make all domains cost `minPrice`! - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| length | uint256 | The maximum length to set | - - -### setPrecisionMultiplier - -```solidity -function setPrecisionMultiplier(uint256 multiplier) public -``` - - -Sets the precision multiplier for the price calculation. -Multiplier This should be picked based on the number of token decimals -to calculate properly. -e.g. if we use a token with 18 decimals, and want precision of 2, -our precision multiplier will be equal to `10^(18 - 2) = 10^16` -Fires `PrecisionMultiplierSet` event. -Only ADMIN can call this function. -> Multiplier should be less or equal to 10^18 and greater than 0! - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| multiplier | uint256 | The multiplier to set | - - -### setRegistrationFeePercentage - -```solidity -function setRegistrationFeePercentage(uint256 regFeePercentage) external -``` - - -Sets the fee percentage for domain registration. - -Fee percentage is set according to the basis of 10000, outlined in ``PERCENTAGE_BASIS``. -Fires ``FeePercentageSet`` event. -Only ADMIN can call this function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| regFeePercentage | uint256 | The fee percentage to set | - - -### setAccessController - -```solidity -function setAccessController(address accessController_) external -``` - - -Sets the access controller for the contract. -Only ADMIN can call this function. -Fires `AccessControllerSet` event. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController_ | address | The address of the new access controller | - - -### getAccessController - -```solidity -function getAccessController() external view returns (address) -``` - - -Getter for ZNSAccessController address stored on this contract. - - - - -### _getPrice - -```solidity -function _getPrice(uint256 length) internal view returns (uint256) -``` - - -Internal function to calculate price based on the config set, -and the length of the domain label. - -Before we calculate the price, 3 different cases are possible: -1. `baseLength` is 0, which means we are returning `maxPrice` as a specific price for all domains -2. `length` is less than or equal to `baseLength`, which means a domain will cost `maxPrice` -3. `length` is greater than `maxLength`, which means a domain will cost `minPrice` - -The formula itself creates an asymptotic curve that decreases in pricing based on domain name length, -base length and max price, the result is divided by the precision multiplier to remove numbers beyond -what we care about, then multiplied by the same precision multiplier to get the actual value -with truncated values past precision. So having a value of `15.235234324234512365 * 10^18` -with precision `2` would give us `15.230000000000000000 * 10^18` - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| length | uint256 | The length of the domain name | - - -### _validateConfig - -```solidity -function _validateConfig() internal view -``` - - -Internal function called every time we set props of `rootDomainPriceConfig` -to make sure that values being set can not disrupt the price curve or zero out prices -for domains. If this validation fails, function will revert. - -We are checking here for possible price spike at `maxLength` -which can occur if some of the config values are not properly chosen and set. - - - -### _authorizeUpgrade - -```solidity -function _authorizeUpgrade(address newImplementation) internal view -``` - - -To use UUPS proxy we override this function and revert if `msg.sender` isn't authorized - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| newImplementation | address | The new implementation contract to upgrade to. | - - - diff --git a/docs/contracts/distribution/ZNSRegistrar.md b/docs/contracts/distribution/ZNSRegistrar.md deleted file mode 100644 index 4a4102373..000000000 --- a/docs/contracts/distribution/ZNSRegistrar.md +++ /dev/null @@ -1,329 +0,0 @@ -## ZNSRegistrar - - -**Main entry point for the three main flows of ZNS - Register, Reclaim and Revoke a domain.** - -This contract serves as the "umbrella" for many ZNS operations, it is given REGISTRAR_ROLE -to combine multiple calls/operations between different modules to achieve atomic state changes -and proper logic for the ZNS flows. You can see functions in other modules that are only allowed -to be called by this contract to ensure proper management of ZNS data in multiple places. -RRR - Register, Reclaim, Revoke start here and then call other modules to complete the flow. -ZNSRegistrar stores most of the other contract addresses and can communicate with other modules, -but the relationship is one-sided, where other modules do not need to know about the ZNSRegistrar, -they only check REGISTRAR_ROLE that can, in theory, be assigned to any other address. - - - - -### registry - -```solidity -contract IZNSRegistry registry -``` - - - - - - - -### treasury - -```solidity -contract IZNSTreasury treasury -``` - - - - - - - -### domainToken - -```solidity -contract IZNSDomainToken domainToken -``` - - - - - - - -### addressResolver - -```solidity -contract IZNSAddressResolver addressResolver -``` - - - - - - - -### onlyNameOwner - -```solidity -modifier onlyNameOwner(bytes32 domainHash) -``` - - -Ensures only the owner of the Name in ZNSRegistry can call. - - - - -### onlyTokenOwner - -```solidity -modifier onlyTokenOwner(bytes32 domainHash) -``` - - -Ensures only the owner of the Tame in ZNSDomainToken can call. - - - - -### initialize - -```solidity -function initialize(address accessController_, address registry_, address treasury_, address domainToken_, address addressResolver_) public -``` - - -Create an instance of the ZNSRegistrar -for registering, reclaiming and revoking ZNS domains - -Instead of direct assignments, we are calling the setter functions -to apply Access Control and ensure only the ADMIN can set the addresses. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController_ | address | Address of the ZNSAccessController contract | -| registry_ | address | Address of the ZNSRegistry contract | -| treasury_ | address | Address of the ZNSTreasury contract | -| domainToken_ | address | Address of the ZNSDomainToken contract | -| addressResolver_ | address | Address of the ZNSAddressResolver contract | - - -### registerDomain - -```solidity -function registerDomain(string name, address domainAddress) external returns (bytes32) -``` - - -This function is the main entry point for the Register flow. -Registers a new domain such as `0://wilder`. -Gets domain hash as a keccak256 hash of the domain label string casted to bytes32, -checks existence of the domain in the registry and reverts if it exists. -Calls `ZNSTreasury` to do the staking part, gets `tokenId` for the new token to be minted -as domain hash casted to uint256, mints the token and sets the domain data in the `ZNSRegistry` -and, possibly, `ZNSAddressResolver`. Emits a `DomainRegistered` event. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| name | string | Name (label) of the domain to register | -| domainAddress | address | Address for the `ZNSAddressResolver` to return when requested (optional, send 0x0 if not needed) | - - -### revokeDomain - -```solidity -function revokeDomain(bytes32 domainHash) external -``` - - -This function is the main entry point for the Revoke flow. -Revokes a domain such as `0://wilder`. -Gets `tokenId` from casted domain hash to uint256, calls `ZNSDomainToken` to burn the token, -deletes the domain data from the `ZNSRegistry` and calls `ZNSTreasury` to unstake and withdraw funds -user staked for the domain. Emits a `DomainRevoked` event. - -> Note that we are not clearing the data in `ZNSAddressResolver` as it is considered not necessary -since none other contracts will have the domain data on them. -If we are not clearing `ZNSAddressResolver` state slots, we are making the next Register transaction -for the same name cheaper, since SSTORE on a non-zero slot costs 5k gas, while SSTORE on a zero slot costs 20k gas. -If a user wants to clear his data from `ZNSAddressResolver`, he can call `ZNSAddressResolver` directly himself -BEFORE he calls to revoke, otherwise, `ZNSRegistry` owner check will fail, since the owner there -will be 0x0 address. -Also note that in order to Revoke, a caller has to be the owner of both: -Name (in `ZNSRegistry`) and Token (in `ZNSDomainToken`). - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | Hash of the domain to revoke | - - -### reclaimDomain - -```solidity -function reclaimDomain(bytes32 domainHash) external -``` - - -This function is the main entry point for the Reclaim flow. This flow is used to -reclaim full ownership of a domain (through becoming the owner of the Name) from the ownership of the Token. -This is used for different types of ownership transfers, such as: -- domain sale - a user will sell the Token, then the new owner has to call this function to reclaim the Name -- domain transfer - a user will transfer the Token, then the new owner has to call this function to reclaim the Name - -A user needs to only be the owner of the Token to be able to Reclaim. -Updates the domain owner in the `ZNSRegistry` to the owner of the token and emits a `DomainReclaimed` event. - - - - -### setRegistry - -```solidity -function setRegistry(address registry_) public -``` - - -Setter function for the `ZNSRegistry` address in state. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| registry_ | address | Address of the `ZNSRegistry` contract | - - -### setTreasury - -```solidity -function setTreasury(address treasury_) public -``` - - -Setter function for the `ZNSTreasury` address in state. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| treasury_ | address | Address of the `ZNSTreasury` contract | - - -### setDomainToken - -```solidity -function setDomainToken(address domainToken_) public -``` - - -Setter function for the `ZNSDomainToken` address in state. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainToken_ | address | Address of the `ZNSDomainToken` contract | - - -### setAddressResolver - -```solidity -function setAddressResolver(address addressResolver_) public -``` - - -Setter function for the `ZNSAddressResolver` address in state. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| addressResolver_ | address | Address of the `ZNSAddressResolver` contract | - - -### setAccessController - -```solidity -function setAccessController(address accessController_) external -``` - - -Setter function for the `ZNSAccessController` address in state. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController_ | address | Address of the `ZNSAccessController` contract | - - -### getAccessController - -```solidity -function getAccessController() external view returns (address) -``` - - -Getter function for the `ZNSAccessController` address in state. - - - - -### _setDomainData - -```solidity -function _setDomainData(bytes32 domainHash, address owner, address domainAddress) internal -``` - - -Set domain data appropriately for a newly registered domain -If no domain address is given, only the domain owner is set, otherwise -`ZNSAddressResolver` is called to assign an address to the newly registered domain. -If the `domainAddress` is not provided upon registration, a user can call `ZNSAddressResolver.setAddress` -to set the address themselves. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The domain name hash | -| owner | address | The owner of the domain | -| domainAddress | address | The content (source) it resolves to | - - -### _authorizeUpgrade - -```solidity -function _authorizeUpgrade(address newImplementation) internal view -``` - - -To use UUPS proxy we override this function and revert if `msg.sender` isn't authorized - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| newImplementation | address | The implementation contract to upgrade to | - - - diff --git a/docs/contracts/distribution/ZNSTreasury.md b/docs/contracts/distribution/ZNSTreasury.md deleted file mode 100644 index 1dbb84f29..000000000 --- a/docs/contracts/distribution/ZNSTreasury.md +++ /dev/null @@ -1,256 +0,0 @@ -## ZNSTreasury - - -**Contract responsible for all staking operations in ZNS and communication with `ZNSPriceOracle`.** - -This contract it called by `ZNSRegistrar` every time a staking operation is needed. -It stores all data regarding user stakes for domains, and it's also the only contract -that is aware of the `ZNSPriceOracle` which it uses to get pricing data for domains. - - - - -### priceOracle - -```solidity -contract IZNSPriceOracle priceOracle -``` - - -The address of the `ZNSPriceOracle` contract. - - - - -### stakingToken - -```solidity -contract IERC20 stakingToken -``` - - -The address of the payment/staking token. Will be set to $ZERO. - - - - -### zeroVault - -```solidity -address zeroVault -``` - - -Address of the Zero Vault, a wallet or contract which gathers all the registration fees. - - - - -### stakedForDomain - -```solidity -mapping(bytes32 => uint256) stakedForDomain -``` - - -The main mapping of the contract. It stores the amount staked for each domain -which is mapped to the domain hash. -Note that there is no address to which the stake is tied to. Instead, the owner data from `ZNSRegistry` -is used to identify a user who owns the stake. So the staking data is tied to the owner of the Name. -This should be taken into account, since any transfer of the Token to another address, -and the system, allowing them to Reclaim the Name, will also allow them to withdraw the stake. -> Stake is owned by the owner of the Name in `ZNSRegistry`! - - - - -### onlyRegistrar - -```solidity -modifier onlyRegistrar() -``` - - -Modifier used for functions that are only allowed to be called by the `ZNSRegistrar` -or any other address that has REGISTRAR_ROLE. - - - - -### initialize - -```solidity -function initialize(address accessController_, address priceOracle_, address stakingToken_, address zeroVault_) external -``` - - -`ZNSTreasury` proxy state initializer. Note that setter functions are used -instead of direct state variable assignments in order to use proper Access Control -at initialization. Only ADMIN in `ZNSAccessController` can call this function. -For this also, it is important that `ZNSAccessController` is deployed and initialized with role data -before this contract is deployed. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController_ | address | The address of the `ZNSAccessController` contract. | -| priceOracle_ | address | The address of the `ZNSPriceOracle` contract. | -| stakingToken_ | address | The address of the staking token (currently $ZERO). | -| zeroVault_ | address | The address of the Zero Vault - the wallet or contract to collect all the registration fees. | - - -### stakeForDomain - -```solidity -function stakeForDomain(bytes32 domainHash, string domainName, address depositor) external -``` - - -Deposits the stake for a domain. This function is called by `ZNSRegistrar` -when a user wants to Register a domain. It transfers the stake amount and the registration fee -to the contract from the user, and records the staked amount for the domain. -Note that a user has to approve the correct amount of `domainPrice + registrationFee` -for this function to not revert. - -Calls `ZNSPriceOracle` to get the price for the domain name based on it's length, -and to get a proper `registrationFee` as a percentage of the price. -In order to avoid needing 2 different approvals, it withdraws `domainPrice + registrationFee` -to this contract and then transfers the `registrationFee` to the Zero Vault. -Sets the `stakedForDomain` mapping for the domain to the `stakeAmount` and emits a `StakeDeposited` event. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain for which the stake is being deposited. | -| domainName | string | The name of the domain for which the stake is being deposited. | -| depositor | address | The address of the user who is depositing the stake. | - - -### unstakeForDomain - -```solidity -function unstakeForDomain(bytes32 domainHash, address owner) external -``` - - -Withdraws the stake for a domain. This function is called by `ZNSRegistrar` -when a user wants to Revoke a domain. It transfers the stake amount from the contract back to the user, -and deletes the staked amount for the domain in state. -Emits a `StakeWithdrawn` event. -Since we are clearing a slot in storage, gas refund from this operation makes Revoke transactions cheaper. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain for which the stake is being withdrawn. | -| owner | address | The address of the user who is withdrawing the stake. | - - -### setZeroVaultAddress - -```solidity -function setZeroVaultAddress(address zeroVault_) public -``` - - -Setter function for the `zeroVault` state variable. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| zeroVault_ | address | The address of the new Zero Vault - the wallet or contract to collect all the fees. | - - -### setPriceOracle - -```solidity -function setPriceOracle(address priceOracle_) public -``` - - -Setter function for the `priceOracle` state variable. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| priceOracle_ | address | The address of the new `ZNSPriceOracle` contract. | - - -### setStakingToken - -```solidity -function setStakingToken(address stakingToken_) public -``` - - -Setter function for the `stakingToken` state variable. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| stakingToken_ | address | The address of the new staking token (currently $ZERO). | - - -### setAccessController - -```solidity -function setAccessController(address accessController_) public -``` - - -Setter function for the `accessController` state variable. -Only ADMIN in `ZNSAccessController` can call this function. - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController_ | address | The address of the new `ZNSAccessController` contract. | - - -### getAccessController - -```solidity -function getAccessController() external view returns (address) -``` - - -Getter function for the `accessController` state variable inherited from `AccessControlled`. - - - - -### _authorizeUpgrade - -```solidity -function _authorizeUpgrade(address newImplementation) internal view -``` - - -To use UUPS proxy we override this function and revert if `msg.sender` isn't authorized - - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| newImplementation | address | The implementation contract to upgrade to | - - - diff --git a/docs/contracts/price/IZNSCurvePricer.md b/docs/contracts/price/IZNSCurvePricer.md index 05e8955f4..a0975bf81 100644 --- a/docs/contracts/price/IZNSCurvePricer.md +++ b/docs/contracts/price/IZNSCurvePricer.md @@ -153,7 +153,7 @@ function initialize(address accessController_, address registry_, struct ICurveP ### getPrice ```solidity -function getPrice(bytes32 parentHash, string label) external view returns (uint256) +function getPrice(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256) ``` @@ -161,6 +161,13 @@ function getPrice(bytes32 parentHash, string label) external view returns (uint2 `parentHash` param is here to allow pricer contracts to have different price configs for different subdomains +`skipValidityCheck` param is added to provide proper revert when the user is +calling this to find out the price of a domain that is not valid. But in Registrar contracts +we want to do this explicitly and before we get the price to have lower tx cost for reverted tx. +So Registrars will pass this bool as "true" to not repeat the validity check. +Note that if calling this function directly to find out the price, a user should always pass "false" +as `skipValidityCheck` param, otherwise, the price will be returned for an invalid label that is not +possible to register. @@ -180,7 +187,7 @@ Fees are only supported for PaymentType.STAKE ! ### getPriceAndFee ```solidity -function getPriceAndFee(bytes32 parentHash, string label) external view returns (uint256 price, uint256 stakeFee) +function getPriceAndFee(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256 price, uint256 stakeFee) ``` diff --git a/docs/contracts/price/IZNSFixedPricer.md b/docs/contracts/price/IZNSFixedPricer.md index 77f6066a8..8654774d4 100644 --- a/docs/contracts/price/IZNSFixedPricer.md +++ b/docs/contracts/price/IZNSFixedPricer.md @@ -62,21 +62,10 @@ Emitted when the `PriceConfig.feePercentage` is set in state for a specific `dom struct PriceConfig { uint256 price; uint256 feePercentage; + bool isSet; } ``` -### priceConfigs - -```solidity -function priceConfigs(bytes32 domainHash) external view returns (uint256 price, uint256 feePercentage) -``` - - - - - - - ### initialize ```solidity @@ -104,7 +93,7 @@ function setPrice(bytes32 domainHash, uint256 _price) external ### getPrice ```solidity -function getPrice(bytes32 parentHash, string label) external view returns (uint256) +function getPrice(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256) ``` @@ -112,6 +101,13 @@ function getPrice(bytes32 parentHash, string label) external view returns (uint2 `parentHash` param is here to allow pricer contracts to have different price configs for different subdomains +`skipValidityCheck` param is added to provide proper revert when the user is +calling this to find out the price of a domain that is not valid. But in Registrar contracts +we want to do this explicitly and before we get the price to have lower tx cost for reverted tx. +So Registrars will pass this bool as "true" to not repeat the validity check. +Note that if calling this function directly to find out the price, a user should always pass "false" +as `skipValidityCheck` param, otherwise, the price will be returned for an invalid label that is not +possible to register. @@ -143,7 +139,7 @@ Fees are only supported for PaymentType.STAKE ! ### getPriceAndFee ```solidity -function getPriceAndFee(bytes32 parentHash, string label) external view returns (uint256 price, uint256 fee) +function getPriceAndFee(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256 price, uint256 fee) ``` diff --git a/docs/contracts/price/ZNSCurvePricer.md b/docs/contracts/price/ZNSCurvePricer.md index 1e09ced9c..a7f0a7cdd 100644 --- a/docs/contracts/price/ZNSCurvePricer.md +++ b/docs/contracts/price/ZNSCurvePricer.md @@ -3,9 +3,9 @@ **Implementation of the Curve Pricing, module that calculates the price of a domain based on its length and the rules set by Zero ADMIN. -This module uses an asymptotic curve that starts from `maxPrice` and decreases in price -until it reaches `minPrice` at `maxLength` length of the domain name. Price after `maxLength` -is fixed and always equal to `minPrice`.** +This module uses an asymptotic curve that starts from `maxPrice` for all domains <= `baseLength`. +It then decreases in price, using the calculated price function below, until it reaches `minPrice` +at `maxLength` length of the domain name. Price after `maxLength` is fixed and always equal to `minPrice`.** @@ -38,6 +38,18 @@ Zero, for pricing root domains, uses this mapping as well under 0x0 hash. +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity @@ -65,12 +77,19 @@ Only Owner of the 0x0 hash (Zero owned address) can call this function. ### getPrice ```solidity -function getPrice(bytes32 parentHash, string label) public view returns (uint256) +function getPrice(bytes32 parentHash, string label, bool skipValidityCheck) public view returns (uint256) ``` Get the price of a given domain name +`skipValidityCheck` param is added to provide proper revert when the user is +calling this to find out the price of a domain that is not valid. But in Registrar contracts +we want to do this explicitly and before we get the price to have lower tx cost for reverted tx. +So Registrars will pass this bool as "true" to not repeat the validity check. +Note that if calling this function directly to find out the price, a user should always pass "false" +as `skipValidityCheck` param, otherwise, the price will be returned for an invalid label that is not +possible to register. #### Parameters @@ -78,6 +97,7 @@ Get the price of a given domain name | ---- | ---- | ----------- | | parentHash | bytes32 | The hash of the parent domain under which price is determined | | label | string | The label of the subdomain candidate to get the price for before/during registration | +| skipValidityCheck | bool | If true, skips the validity check for the label | ### getFeeForPrice @@ -103,7 +123,7 @@ based on the value set by the owner of the parent domain. ### getPriceAndFee ```solidity -function getPriceAndFee(bytes32 parentHash, string label) external view returns (uint256 price, uint256 stakeFee) +function getPriceAndFee(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256 price, uint256 stakeFee) ``` @@ -118,6 +138,7 @@ under the given parent. | ---- | ---- | ----------- | | parentHash | bytes32 | The hash of the parent domain under which price and fee are determined | | label | string | The label of the subdomain candidate to get the price and fee for before/during registration | +| skipValidityCheck | bool | | ### setPriceConfig @@ -132,6 +153,8 @@ Setter for `priceConfigs[domainHash]`. Only domain owner/operator can call this Validates the value of the `precisionMultiplier` and the whole config in order to avoid price spikes, fires `PriceConfigSet` event. Only ADMIN can call this function. +> This function should ALWAYS be used to set the config, since it's the only place where `isSet` is set to true. +> Use the other individual setters to modify only, since they do not set this variable! #### Parameters @@ -261,7 +284,7 @@ Only domain owner/operator can call this function. ### setFeePercentage ```solidity -function setFeePercentage(bytes32 domainHash, uint256 feePercentage) external +function setFeePercentage(bytes32 domainHash, uint256 feePercentage) public ``` @@ -302,10 +325,11 @@ function _getPrice(bytes32 parentHash, uint256 length) internal view returns (ui Internal function to calculate price based on the config set, and the length of the domain label. -Before we calculate the price, 3 different cases are possible: -1. `baseLength` is 0, which means we are returning `maxPrice` as a specific price for all domains -2. `length` is less than or equal to `baseLength`, which means a domain will cost `maxPrice` -3. `length` is greater than `maxLength`, which means a domain will cost `minPrice` +Before we calculate the price, 4 different cases are possible: +1. `maxPrice` is 0, which means all subdomains under this parent are free +2. `baseLength` is 0, which means we are returning `maxPrice` as a specific price for all domains +3. `length` is less than or equal to `baseLength`, which means a domain will cost `maxPrice` +4. `length` is greater than `maxLength`, which means a domain will cost `minPrice` The formula itself creates an asymptotic curve that decreases in pricing based on domain name length, base length and max price, the result is divided by the precision multiplier to remove numbers beyond diff --git a/docs/contracts/price/ZNSFixedPricer.md b/docs/contracts/price/ZNSFixedPricer.md index 9e044f302..4d1870f02 100644 --- a/docs/contracts/price/ZNSFixedPricer.md +++ b/docs/contracts/price/ZNSFixedPricer.md @@ -32,6 +32,18 @@ Mapping of domainHash to price config set by the domain owner/operator +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity @@ -65,12 +77,19 @@ Sets the price for a domain. Only callable by domain owner/operator. Emits a `Pr ### getPrice ```solidity -function getPrice(bytes32 parentHash, string label) public view returns (uint256) +function getPrice(bytes32 parentHash, string label, bool skipValidityCheck) public view returns (uint256) ``` Gets the price for a subdomain candidate label under the parent domain. +`skipValidityCheck` param is added to provide proper revert when the user is +calling this to find out the price of a domain that is not valid. But in Registrar contracts +we want to do this explicitly and before we get the price to have lower tx cost for reverted tx. +So Registrars will pass this bool as "true" to not repeat the validity check. +Note that if calling this function directly to find out the price, a user should always pass "false" +as `skipValidityCheck` param, otherwise, the price will be returned for an invalid label that is not +possible to register. #### Parameters @@ -78,6 +97,7 @@ Gets the price for a subdomain candidate label under the parent domain. | ---- | ---- | ----------- | | parentHash | bytes32 | The hash of the parent domain to check the price under | | label | string | The label of the subdomain candidate to check the price for | +| skipValidityCheck | bool | If true, skips the validity check for the label | ### setFeePercentage @@ -87,7 +107,8 @@ function setFeePercentage(bytes32 domainHash, uint256 feePercentage) public ``` -Sets the feePercentage for a domain. Only callable by domain owner/operator. Emits a `FeePercentageSet` event. +Sets the feePercentage for a domain. Only callable by domain owner/operator. +Emits a `FeePercentageSet` event. `feePercentage` is set as a part of the `PERCENTAGE_BASIS` of 10,000 where 1% = 100 @@ -110,6 +131,8 @@ Setter for `priceConfigs[domainHash]`. Only domain owner/operator can call this Sets both `PriceConfig.price` and `PriceConfig.feePercentage` in one call, fires `PriceSet` and `FeePercentageSet` events. +> This function should ALWAYS be used to set the config, since it's the only place where `isSet` is set to true. +> Use the other individual setters to modify only, since they do not set this variable! #### Parameters @@ -142,7 +165,7 @@ based on the value set by the owner of the parent domain. ### getPriceAndFee ```solidity -function getPriceAndFee(bytes32 parentHash, string label) external view returns (uint256 price, uint256 fee) +function getPriceAndFee(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256 price, uint256 fee) ``` @@ -157,6 +180,7 @@ under the given parent. | ---- | ---- | ----------- | | parentHash | bytes32 | The hash of the parent domain under which price and fee are determined | | label | string | The label of the subdomain candidate to get the price and fee for before/during registration | +| skipValidityCheck | bool | If true, skips the validity check for the label | ### setRegistry @@ -172,6 +196,42 @@ This function is required for all contracts inheriting `ARegistryWired`. +### _setPrice + +```solidity +function _setPrice(bytes32 domainHash, uint256 price) internal +``` + + +Internal function for set price + + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| domainHash | bytes32 | The hash of the domain | +| price | uint256 | The new price | + + +### _setFeePercentage + +```solidity +function _setFeePercentage(bytes32 domainHash, uint256 feePercentage) internal +``` + + +Internal function for setFeePercentage + + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| domainHash | bytes32 | The hash of the domain | +| feePercentage | uint256 | The new feePercentage | + + ### _authorizeUpgrade ```solidity diff --git a/docs/contracts/registrar/IZNSSubRegistrar.md b/docs/contracts/registrar/IZNSSubRegistrar.md index 68e175f22..7610f3cf1 100644 --- a/docs/contracts/registrar/IZNSSubRegistrar.md +++ b/docs/contracts/registrar/IZNSSubRegistrar.md @@ -68,6 +68,18 @@ Emitted when a `mintlist` is updated for a domain. +### MintlistCleared + +```solidity +event MintlistCleared(bytes32 domainHash) +``` + + + + + + + ### RootRegistrarSet ```solidity @@ -92,10 +104,10 @@ function distrConfigs(bytes32 domainHash) external view returns (contract IZNSPr -### mintlist +### isMintlistedForDomain ```solidity -function mintlist(bytes32 domainHash, address candidate) external view returns (bool) +function isMintlistedForDomain(bytes32 domainHash, address candidate) external view returns (bool) ``` @@ -200,6 +212,30 @@ function updateMintlistForDomain(bytes32 domainHash, address[] candidates, bool[ +### clearMintlistForDomain + +```solidity +function clearMintlistForDomain(bytes32 domainHash) external +``` + + + + + + + +### clearMintlistAndLock + +```solidity +function clearMintlistAndLock(bytes32 domainHash) external +``` + + + + + + + ### setRegistry ```solidity diff --git a/docs/contracts/registrar/ZNSRootRegistrar.md b/docs/contracts/registrar/ZNSRootRegistrar.md index fe22797cf..46d462a78 100644 --- a/docs/contracts/registrar/ZNSRootRegistrar.md +++ b/docs/contracts/registrar/ZNSRootRegistrar.md @@ -77,6 +77,18 @@ contract IZNSSubRegistrar subRegistrar +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity @@ -370,18 +382,6 @@ Only ADMIN in `ZNSAccessController` can call this function. | addressResolver_ | address | Address of the `ZNSAddressResolver` contract | -### _isValidString - -```solidity -function _isValidString(string str) internal pure returns (bool) -``` - - - - - - - ### _authorizeUpgrade ```solidity diff --git a/docs/contracts/registrar/ZNSSubRegistrar.md b/docs/contracts/registrar/ZNSSubRegistrar.md index 9adbd15c9..1bd11eccc 100644 --- a/docs/contracts/registrar/ZNSSubRegistrar.md +++ b/docs/contracts/registrar/ZNSSubRegistrar.md @@ -37,10 +37,26 @@ Note that the rules outlined in the DistributionConfig are only applied to direc +### Mintlist + + + + + + + + +```solidity +struct Mintlist { + mapping(uint256 => mapping(address => bool)) list; + uint256 ownerIndex; +} +``` + ### mintlist ```solidity -mapping(bytes32 => mapping(address => bool)) mintlist +mapping(bytes32 => struct ZNSSubRegistrar.Mintlist) mintlist ``` @@ -63,6 +79,18 @@ modifier onlyOwnerOperatorOrRegistrar(bytes32 domainHash) +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity @@ -119,7 +147,8 @@ function setDistributionConfigForDomain(bytes32 domainHash, struct IDistribution ``` -Setter for `distrConfigs[domainHash]`. Only domain owner/operator or ZNSRootRegistrar can call this function. +Setter for `distrConfigs[domainHash]`. +Only domain owner/operator or ZNSRootRegistrar can call this function. This config can be changed by the domain owner/operator at any time or be set after registration if the config was not provided during the registration. @@ -175,24 +204,10 @@ Fires `PaymentTypeSet` event. | paymentType | enum IDistributionConfig.PaymentType | The new payment type to set | -### _setAccessTypeForDomain - -```solidity -function _setAccessTypeForDomain(bytes32 domainHash, enum IDistributionConfig.AccessType accessType) internal -``` - - - - -Internal function used by this contract to set the access type for a subdomain -during revocation process. - - - ### setAccessTypeForDomain ```solidity -function setAccessTypeForDomain(bytes32 domainHash, enum IDistributionConfig.AccessType accessType) external +function setAccessTypeForDomain(bytes32 domainHash, enum IDistributionConfig.AccessType accessType) public ``` @@ -233,6 +248,42 @@ Fires `MintlistUpdated` event. | allowed | bool[] | The array of booleans indicating whether to add or remove the candidate | +### isMintlistedForDomain + +```solidity +function isMintlistedForDomain(bytes32 domainHash, address candidate) external view returns (bool) +``` + + + + + + + +### clearMintlistForDomain + +```solidity +function clearMintlistForDomain(bytes32 domainHash) public +``` + + + + + + + +### clearMintlistAndLock + +```solidity +function clearMintlistAndLock(bytes32 domainHash) external +``` + + + + + + + ### setRegistry ```solidity diff --git a/docs/contracts/registry/IZNSRegistry.md b/docs/contracts/registry/IZNSRegistry.md index b848b249f..7e0e93ca4 100644 --- a/docs/contracts/registry/IZNSRegistry.md +++ b/docs/contracts/registry/IZNSRegistry.md @@ -108,14 +108,9 @@ function initialize(address accessController) external ``` -Create an instance of the ZNSRegistry contract -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| accessController | address | The addrss of the access controller | ### exists @@ -125,14 +120,9 @@ function exists(bytes32 domainHash) external view returns (bool) ``` -Check if a given domain exists -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of a domain's name | ### isOwnerOrOperator @@ -142,15 +132,9 @@ function isOwnerOrOperator(bytes32 domainHash, address candidate) external view ``` -Checks if provided address is an owner or an operator of the provided domain -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of a domain's name | -| candidate | address | The address for which we are checking access | ### isOperatorFor @@ -191,14 +175,9 @@ function getDomainRecord(bytes32 domainHash) external view returns (struct IZNSR ``` -Get a record for a domain -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | the hash of a domain's name | ### getDomainOwner @@ -208,14 +187,9 @@ function getDomainOwner(bytes32 domainHash) external view returns (address) ``` -Get the owner of the given domain -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | the hash of a domain's name | ### getDomainResolver @@ -225,14 +199,9 @@ function getDomainResolver(bytes32 domainHash) external view returns (address) ``` -Get the default resolver for the given domain -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of a domain's name | ### createDomainRecord @@ -242,16 +211,9 @@ function createDomainRecord(bytes32 domainHash, address owner, address resolver) ``` -Create a new domain record -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain name | -| owner | address | The owner of the new domain | -| resolver | address | The resolver of the new domain | ### updateDomainRecord @@ -261,16 +223,9 @@ function updateDomainRecord(bytes32 domainHash, address owner, address resolver) ``` -Update an existing domain record's owner or resolver -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain | -| owner | address | The owner or an allowed operator of that domain | -| resolver | address | The resolver for the domain | ### updateDomainOwner @@ -280,15 +235,9 @@ function updateDomainOwner(bytes32 domainHash, address owner) external ``` -Update a domain's owner -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | the hash of a domain's name | -| owner | address | The account to transfer ownership to | ### updateDomainResolver @@ -298,15 +247,9 @@ function updateDomainResolver(bytes32 domainHash, address resolver) external ``` -Update the domain's default resolver -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | the hash of a domain's name | -| resolver | address | The new default resolver | ### deleteRecord @@ -316,14 +259,9 @@ function deleteRecord(bytes32 domainHash) external ``` -Delete a domain's record -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The hash of the domain name | diff --git a/docs/contracts/registry/ZNSRegistry.md b/docs/contracts/registry/ZNSRegistry.md index a8df2f79e..efcbe46f1 100644 --- a/docs/contracts/registry/ZNSRegistry.md +++ b/docs/contracts/registry/ZNSRegistry.md @@ -65,6 +65,23 @@ modifier onlyOwner(bytes32 domainHash) Revert if `msg.sender` is not the owner. Used for owner restricted functions. +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| domainHash | bytes32 | the hash of a domain's name | + + +### constructor + +```solidity +constructor() public +``` + + + + + ### initialize @@ -76,7 +93,7 @@ function initialize(address accessController_) external Initializer for the `ZNSRegistry` proxy. -! The owner of the 0x0 hash should be a multisig ! +! The owner of the 0x0 hash should be a multisig ideally, but EOA can be used to deploy ! > Admin account deploying the contract will be the owner of the 0x0 hash ! #### Parameters diff --git a/docs/contracts/resolver/IZNSAddressResolver.md b/docs/contracts/resolver/IZNSAddressResolver.md index fbbdb3731..ed5703144 100644 --- a/docs/contracts/resolver/IZNSAddressResolver.md +++ b/docs/contracts/resolver/IZNSAddressResolver.md @@ -35,14 +35,7 @@ function supportsInterface(bytes4 interfaceId) external view returns (bool) -ERC-165 check for implementation identifier -Supports interfaces IZNSAddressResolver and IERC165 -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| interfaceId | bytes4 | ID to check, XOR of the first 4 bytes of each function signature | ### getAddress @@ -54,13 +47,7 @@ function getAddress(bytes32 domainHash) external view returns (address) -Resolves address given domain name hash -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The identifying hash of a domain's name | ### setAddress @@ -72,14 +59,7 @@ function setAddress(bytes32 domainHash, address newAddress) external -Sets the address of a domain name hash, only registry -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| domainHash | bytes32 | The identifying hash of a domain's name | -| newAddress | address | The new domain owner | ### getInterfaceId @@ -113,15 +93,9 @@ function initialize(address _accessController, address _registry) external ``` -Initialize an instance of the ZNSAddressResolver -#### Parameters -| Name | Type | Description | -| ---- | ---- | ----------- | -| _accessController | address | The access controller | -| _registry | address | The registry address | diff --git a/docs/contracts/resolver/ZNSAddressResolver.md b/docs/contracts/resolver/ZNSAddressResolver.md index 26da07001..9abe50cfa 100644 --- a/docs/contracts/resolver/ZNSAddressResolver.md +++ b/docs/contracts/resolver/ZNSAddressResolver.md @@ -22,6 +22,18 @@ to Ethereum wallets or contracts registered in ZNS. +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity diff --git a/docs/contracts/token/ZNSDomainToken.md b/docs/contracts/token/ZNSDomainToken.md index f166d712f..a40bbcf2c 100644 --- a/docs/contracts/token/ZNSDomainToken.md +++ b/docs/contracts/token/ZNSDomainToken.md @@ -11,6 +11,18 @@ the `ZNSRootRegistrar.sol` contract or any address holding a REGISTRAR_ROLE. +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity @@ -175,9 +187,15 @@ function supportsInterface(bytes4 interfaceId) public view virtual returns (bool ``` +To allow for user extension of the protocol we have to +enable checking acceptance of new interfaces to ensure they are supported +#### Parameters +| Name | Type | Description | +| ---- | ---- | ----------- | +| interfaceId | bytes4 | The interface ID | ### _burn @@ -187,9 +205,14 @@ function _burn(uint256 tokenId) internal ``` +ERC721 `_burn` function +#### Parameters +| Name | Type | Description | +| ---- | ---- | ----------- | +| tokenId | uint256 | The ID of the token to burn | ### _baseURI @@ -199,12 +222,9 @@ function _baseURI() internal view returns (string) ``` +Return the baseURI -Base URI for computing {tokenURI}. If set, the resulting URI for each -token will be the concatenation of the `baseURI` and the `tokenId`. Empty -by default, can be overridden in child contracts. - ### _authorizeUpgrade diff --git a/docs/contracts/treasury/ZNSTreasury.md b/docs/contracts/treasury/ZNSTreasury.md index aecee6583..9a7bf5093 100644 --- a/docs/contracts/treasury/ZNSTreasury.md +++ b/docs/contracts/treasury/ZNSTreasury.md @@ -33,16 +33,28 @@ mapping(bytes32 => struct IZNSTreasury.Stake) stakedForDomain ``` -The mapping that stores `Stake` struct mapped by domainHash. It stores the staking data for each domain in zNS. -Note that there is no owner address to which the stake is tied to. Instead, the owner data from `ZNSRegistry` -is used to identify a user who owns the stake. So the staking data is tied to the owner of the Name. -This should be taken into account, since any transfer of the Token to another address, -and the system, allowing them to Reclaim the Name, will also allow them to withdraw the stake. +The mapping that stores `Stake` struct mapped by domainHash. It stores the staking data for +each domain in zNS. Note that there is no owner address to which the stake is tied to. Instead, the +owner data from `ZNSRegistry` is used to identify a user who owns the stake. So the staking data is +tied to the owner of the Name. This should be taken into account, since any transfer of the Token to +another address, and the system, allowing them to Reclaim the Name, will also allow them to withdraw the stake. > Stake is owned by the owner of the Name in `ZNSRegistry` which the owner of the Token can reclaim! +### constructor + +```solidity +constructor() public +``` + + + + + + + ### initialize ```solidity @@ -131,8 +143,8 @@ An alternative to `stakeForDomain()` for cases when a parent domain is using Pay Note that `stakeFee` transfers are NOT present here, since a fee on top of the price is ONLY supported for STAKE payment type. This function is called by `ZNSRootRegistrar.sol` when a user wants to register a domain. -This function uses a different approach than `stakeForDomain()` as it performs 2 transfers from the user's wallet. -Is uses `paymentConfigs[parentHash]` to get the token and beneficiary for the parent domain. +This function uses a different approach than `stakeForDomain()` as it performs 2 transfers from the user's +wallet. Is uses `paymentConfigs[parentHash]` to get the token and beneficiary for the parent domain. Can be called ONLY by the REGISTRAR_ROLE. Fires a `DirectPaymentProcessed` event. #### Parameters @@ -216,6 +228,30 @@ This function is required for all contracts inheriting `ARegistryWired`. +### _setBeneficiary + +```solidity +function _setBeneficiary(bytes32 domainHash, address beneficiary) internal +``` + + + + + + + +### _setPaymentToken + +```solidity +function _setPaymentToken(bytes32 domainHash, address paymentToken) internal +``` + + + + + + + ### _authorizeUpgrade ```solidity diff --git a/docs/contracts/types/ICurvePriceConfig.md b/docs/contracts/types/ICurvePriceConfig.md index 3e5636290..4f7a31a62 100644 --- a/docs/contracts/types/ICurvePriceConfig.md +++ b/docs/contracts/types/ICurvePriceConfig.md @@ -34,6 +34,7 @@ struct CurvePriceConfig { uint256 baseLength; uint256 precisionMultiplier; uint256 feePercentage; + bool isSet; } ``` diff --git a/docs/contracts/types/IDistributionConfig.md b/docs/contracts/types/IDistributionConfig.md index 42d157100..9c9208467 100644 --- a/docs/contracts/types/IDistributionConfig.md +++ b/docs/contracts/types/IDistributionConfig.md @@ -1,7 +1,8 @@ ## IDistributionConfig -**IDistributionConfig.sol - An interface containing all types required for distribution configuration of a domain.** +**IDistributionConfig.sol - An interface containing all types required for +distribution configuration of a domain.** @@ -9,7 +10,8 @@ Types outlined in this config are stored on the `ZNSSubRegistrar` contract and a how subdomains are distributed for each parent domain. Below are docs for the types in this file: - `DistributionConfig`: Struct containing the configuration data for a parent domain: - + `pricerContract`: The address of the pricer contract chosen by the owner of the parent domain (IZNSPricer type required!) + + `pricerContract`: The address of the pricer contract chosen by the owner of the + parent domain (IZNSPricer type required!) + `paymentType`: The payment type chosen by the owner of the parent domain + `accessType`: The access type chosen by the owner of the parent domain - `AccessType`: Enum signifying the access type of a parent domain: diff --git a/docs/contracts/types/IZNSPricer.md b/docs/contracts/types/IZNSPricer.md index 945280222..3f57a8567 100644 --- a/docs/contracts/types/IZNSPricer.md +++ b/docs/contracts/types/IZNSPricer.md @@ -11,7 +11,7 @@ Base interface required to be inherited by all Pricing contracts to work with zN ### getPrice ```solidity -function getPrice(bytes32 parentHash, string label) external view returns (uint256) +function getPrice(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256) ``` @@ -19,13 +19,20 @@ function getPrice(bytes32 parentHash, string label) external view returns (uint2 `parentHash` param is here to allow pricer contracts to have different price configs for different subdomains +`skipValidityCheck` param is added to provide proper revert when the user is +calling this to find out the price of a domain that is not valid. But in Registrar contracts +we want to do this explicitly and before we get the price to have lower tx cost for reverted tx. +So Registrars will pass this bool as "true" to not repeat the validity check. +Note that if calling this function directly to find out the price, a user should always pass "false" +as `skipValidityCheck` param, otherwise, the price will be returned for an invalid label that is not +possible to register. ### getPriceAndFee ```solidity -function getPriceAndFee(bytes32 parentHash, string label) external view returns (uint256 price, uint256 fee) +function getPriceAndFee(bytes32 parentHash, string label, bool skipValidityCheck) external view returns (uint256 price, uint256 fee) ```