On-chain storage of metadata, controlled by name-based NFTs
Domain-based record system to store essential metadata on-chain. An ERC721 NFT is issued for the owner of domain record, allowing on-chain governance for a system which uses CRS as a canonic source of truth for it's data. It's an adapted fork of Ethereum Name Service.
All web3 interactions are using default window.ethereum web3 provider.
It also proxies ethers so you can use the same version in your project.
npm install @le7el/web3_crs
import { ethers, controller, nft, resolver, utils, artifacts } from "@le7el/web3_crs"
The main interface for interaction with CRS NFTs.
#### available(string name, Web3Provider provider = null) returns (boolean promise)
Checks if specific name wasn't registered already.
``js`
await controller.available("VeVerse", CONTROLLER_ADDRESS)
#### makeCommitment(string name, address owner, bytes32 secret, address resolver, address addr, string contract_address, Web3Provider provider = null) returns (bytes32 promise)
Generates commitment hash for the provided secret. Default values for resolver and addr whould be default NFT resolver and owner.
`js`
const owner = "0x0000000000000000000000000000000000000000"
const secret = ethers.utils.randomBytes(32)
const commitment = await controller.makeCommitment("VeVerse", owner, secret, null, null, CONTROLLER_ADDRESS)
#### commit(bytes32 commitment, string contract_address, Web3Provider provider = null) returns (transaction promise)
Start registration of CRS name, there should be 60 seconds delay between commitment and registration to prevent race conditions.
`js`
await controller.commit(commitment, CONTROLLER_ADDRESS)
#### whitelistedCommit(string name, bytes32 commitment, bytes pass, string contract_address, Web3Provider provider = null) returns (transaction promise)
Commitment version with whitelisted pass.
`js`
await controller.commit(name, commitment, pass, CONTROLLER_ADDRESS)
Pass can be generated using the following code:
`js
const permit = async function(privKey, address, name) {
const whitelistMessage = ethers.utils.keccak256(
ethers.utils.defaultAbiCoder.encode(
["bytes32", "address", "string"], [
await controller.getDomainSeparator(CONTROLLER_ADDRESS),
address,
name
],
),
)
const signer = new ethers.Wallet(privKey)
const whitelistSignature = await signer.signMessage(ethers.utils.arrayify(whitelistMessage))
const sig = ethers.utils.splitSignature(
ethers.utils.arrayify(whitelistSignature)
);
const pass = ethers.utils.defaultAbiCoder.encode(
["uint8", "bytes32", "bytes32"], [sig.v, sig.r, sig.s],
)
return pass
}
`
Domain separator can be also generated off-chain using the following code:
`js
function domain(chainId, verifyingContract) {
return {
name: "IdentityWhitelist",
version: "v1",
chainId,
verifyingContract
}
}
const chainId = 1 // Ethereum Mainnet
const contractDomain = ethers.utils._TypedDataEncoder.hashDomain(
domain(chainId, CONTROLLER_ADDRESS)
)
`
#### register(string name, address owner, integer duration, bytes32 secret, address resolver, address addr, string contract_address, Web3Provider provider = null) returns (transaction promise)
All variables should be the same as used on makeCommitment step. Some CRS may require approval of a relevant ERC20 token, before running this transaction. This can be done with utils.erc20Approve call. Default values for resolver and addr whould be default NFT resolver and owner, should be the same values as in makeCommitment.
`js`
const owner = "0x0000000000000000000000000000000000000000"
const duration = 31536000 // 1 year in seconds
await controller.register("VeVerse", owner, duration, secret, null, null, CONTROLLER_ADDRESS)
#### rentPrice(string name, integer duration, string contract_address, Web3Provider provider = null) returns ([address, BigNumber] promise)
Checks if there is any fee to register / renew this CRS record, returns contract address of ERC20 token and the fee amount. In case address is zero, it means that fee should be paid in gas coin, which is managed by register automatically, call erc20Approve if there is non-zero fee in ERC20 token.
Interface to fetch data related to specific NFT.
#### gasFee(integer duration, string contract_address, Web3Provider provider = null) returns ([address, BigNumber] promise)
Checks if there is any fee to register / renew this NFT, returns contract address of ERC20 token and the fee amount. In case address is zero, it means that fee should be paid in gas coin, which is managed by register automatically, call erc20Approve if there is non-zero fee in ERC20 token.
The difference with the rentPrice is that it's paid to the LE7EL DAO, instead of the root domain owner.
#### getName(integer id, string contract_address, Web3Provider provider = null) returns (string promise)
Get human-readable name e.g. johndoe.l7l associated with this NFT id.
#### getMetadata(integer id, string contract_address, Web3Provider provider = null) returns (object promise)
Get full metadata for the NFT by it's id. It includes the name given by getName but is more heavy RPC operation, so if you need just name, use getName.
Sample metadata would look like this:
`json`
{
"name":"johndoe.l7l",
"description":"Ownership of identity record on le7el.com",
"image_data":"",
"attributes":[{"trait_type":"Type","value":"Identity"}]
}
#### getNameExpires(string name, string contract_address, Web3Provider provider = null) returns (BigNumber promise)
Get expire date in timestamp for name registered as CRS record associated with NFT.
Returns the list of NFT ids owned by specific wallet. Ids are returned as strings in a hex form e.g. 0x27cf60eaf7291bc5004051bead7742d568b25692edcfee3d2ee7e1b047c49382
`js`
const nftIds = await getNftsForWallet('0x42b3830ac0781c9dc46d94a2a5a830bd10797aec', '4')
API to get / set values associated with specific NFT.
#### setText(bytes32 node, string key, string value, string resolver_address, Web3Provider provider = null) returns (transaction promise)
Set an arbitary string value associated with specific CRS record, by a string key.
Here we assign "CUSTOM_AVATAR_URL" to johndoe.l7l CRS record:
`js`
await resolver.setText(
0x065942c7a3e13329f007894615b14cf2e9026dc7f015dbd561fbb753c6e5cd1d,
"CUSTOM_AVATAR_URL",
"ipfs://bafybeigkgx3gq5yrrsyxpna2czlq3bc2ish2gk6yqh7v57kugehlq6qoly"
)
#### getText(bytes32 node, string key, string resolver_address, Web3Provider provider = null) returns (string promise)
Get an arbitary string value associated with specific CRS record, by a string key.
To get "CUSTOM_AVATAR_URL" value for johndoe.l7l CRS record:
`js`
const custom_avatar = await resolver.getText(
0x065942c7a3e13329f007894615b14cf2e9026dc7f015dbd561fbb753c6e5cd1d,
"CUSTOM_AVATAR_URL"
)
#### setProxyConfig(bytes32 node, address controller, bytes4 selector, address proxy, string resolver_address, Web3Provider provider = null) returns (transaction promise)
Set proxy contract associated with specific CRS record. Such proxy contracts are used by 3rd parties to attach metadata associated with their project to CRS record without a special user permission.
In the following example CUSTOM_CONTROLLER_ADDRESS is assigning a proxy contract CUSTOM_PROXY_ADDRESS with a method tokenURI to johndoe.l7l CRS record. Only CUSTOM_CONTROLLER_ADDRESS will be able to change CUSTOM_PROXY_ADDRESS in future.
`js`
await resolver.setProxyConfig(
0x065942c7a3e13329f007894615b14cf2e9026dc7f015dbd561fbb753c6e5cd1d,
CUSTOM_CONTROLLER_ADDRESS,
bytes4(keccak256("tokenURI(uint256,string,string)")),
CUSTOM_PROXY_ADDRESS,
RESOLVER_ADDRESS
)
#### getProxyConfig(bytes32 node, address controller, bytes4 selector, string resolver_address, Web3Provider provider = null) returns (string promise)
Get proxy contract associated with specific CRS record. Such proxy contracts are used by 3rd parties to attach metadata associated with their project to CRS record without a special user permission.
To a get custom JSON metadata for NFT in scope of CUSTOM_CONTROLLER_ADDRESS the following code can be used.
`js`
const proxy_address = await resolver.getProxyConfig(
0x065942c7a3e13329f007894615b14cf2e9026dc7f015dbd561fbb753c6e5cd1d,
CUSTOM_CONTROLLER_ADDRESS,
bytes4(keccak256("tokenURI(uint256,string,string)"))
)
const provider = new ethers.providers.Web3Provider(window.ethereum)
const contract = new ethers.Contract(proxy_address, PROXY_ABI, provider)
const myProjectMetadata = await contract.tokenURI(1, "johndoe.l7l", "")
#### initContract(address contract_address, object abi, boolean readOnly, Web3Provider provider = null) returns (ethers.Contract promise)
Initialise contract by address and abi. Pass false to readOnly if you need to publish transactions.
`js`
initContract(controller_address, controllerConfig.abi)
.then(contract => contract.getDomainSeparator())
#### erc20Approve(address token_address, address spender_address, BigNumber amount, Web3Provider provider = null) returns (transaction promise)
Registration may require fees to be paid in native ERC20 token, use this method to authorize such payment before registration. Check BigNumber to pass token amount. You only need this if, controller.rentPrice(...) returns non-zero address as first variable and greater than 0 on second variable e.g.
`js`
controller.rentPrice(name, duration, CONTROLLER_ADDRESS)
.then((response) => {
const token = response[0]
const amount = response[1]
if (token === ADDRESS_ZERO || response[1].isZero()) {
return register(name, accounts[0], duration, secret, null, null, CONTROLLER_ADDRESS)
} else {
return erc20Approve(token, CONTROLLER_ADDRESS, amount)
.then(tr => provider.waitForTransaction(tr.hash))
.then(_ => register(name, accounts[0], duration, secret, null, null, CONTROLLER_ADDRESS))
}
})
#### nameToNode(string name) returns (string)
Convert human-readable name e.g. johndoe.l7l into a node used in CRS resolver.
`js`
const node = nameToNode("johndoe.l7l")
node === "0x065942c7a3e13329f007894615b14cf2e9026dc7f015dbd561fbb753c6e5cd1d"
#### nameToId(string name) returns (string)
Convert human-readable name e.g. johndoe.l7l into an id used for the related NFT. A reserve operation is not possible off-chain, use getName from nft module for that.
`js`
const id = nameToId("johndoe.l7l")
node === "2871587377811694866171220606258498541438397112258729693763861304963081030941"
#### nameToNftId(string name) returns (string)
Convert human-readable name e.g. johndoe into the related NFT id
`jsjohndoe
const id = nameToNftId()`
id === "93179736082580775654606992995456773265844288993353207761363709104151049046407"
#### nodeToId(string name) returns (string)
Convert CRS node e.g. 0x065942c7a3e13329f007894615b14cf2e9026dc7f015dbd561fbb753c6e5cd1d into an id used for the related NFT.
`js`
const id = nodeToId("0x065942c7a3e13329f007894615b14cf2e9026dc7f015dbd561fbb753c6e5cd1d")
node === "2871587377811694866171220606258498541438397112258729693763861304963081030941"
#### idToNode(string name) returns (string)
Convert NFT id e.g. 2871587377811694866171220606258498541438397112258729693763861304963081030941 into CRS node.
`js`
const id = idToNode("2871587377811694866171220606258498541438397112258729693763861304963081030941")
node === "0x065942c7a3e13329f007894615b14cf2e9026dc7f015dbd561fbb753c6e5cd1d"
Provides access to low level data (abi, bytecode etc) for the core smart contracts with the following keys:
* controller
* gatedController
* registry
* nft
* resolver
For instance, to access controller abi, you can use artifacts.controller.abi.
Implementation of the CRS Registry, the central contract used to look up resolvers and owners for domains.
Implementation of ERC721 standard for CRS NFTs, this smart contract is also an owner of CRSRegistry. Protected functions are called through Controller contract, check it's public interface.
The CRS registry is a single central contract that provides a mapping from world names to owners and resolvers, as described in EIP 137.
The CRS operates on 'nodes' instead of human-readable names; a human readable name is converted to a node using the namehash algorithm, which is as follows:
def namehash(name):
if name == '':
return '\0' * 32
else:
label, _, remainder = name.partition('.')
return sha3(namehash(remainder) + sha3(label))
The registry's interface is as follows:
Returns the owner of the specified node.
Returns the resolver for the specified node.
Updates the owner of a node. Only the current owner may call this function.
Updates the owner of a subnode. For instance, the owner of "foo.com" may change the owner of "bar.foo.com" by calling setSubnodeOwner(namehash("foo.com"), sha3("bar"), newowner). Only callable by the owner of node.
Sets the resolver address for the specified node.
Controller smart contract is used to change global NFT settings.
Checks availability of name in namespace.
Calculate price in ERC20 or gas coin for registering CRS record.
Generate commitment hash to reserve name for registration, having hidden secret to confirm ownership.
Start registration process, with commitment hash returned by makeCommitment.
Finish registration process after commitment maturation, use secret hash from makeCommitment.
Extend lease for a currently owned NFT for CRS name.
Withdraw registration fees in ERC20 token or gas coin (address(0) as _paymentToken).
It's possible to limit the lease period for which registrations are allowed by this controller. By default it's 0, which means unlimited leases. To limit registrations and renewals with 1 year period, you should pass 31536000 a number of seconds in a year as a new _maxLeasePeriod.
Extension of NFT controller interface where commitments require validation (whitelisted registration).
and validator signature for your name.getDomainSeparator()
Read-only constant to generate whitelisting passes.
toggleWhitelist(bool _status)
Pass
true to enable commits with a default interface commit(bytes32 _commitment) without whitelisting requirements.addValidator(address _validator)
Add address whose signature would allow registration of a new names.
removeValidator(address _validator)
Remove previously approved validator address.
Resolver interface
Resolver smart contract is modular, with
DefaultResolver having all modules enabled. Projects can implement own resolves using modules from contracts/resolver/profile. It's used as on-chain storage for different kind of data related to specific CRS record.setApprovalForAll(address operator, bool approved)
Allow / Revoke 3rd party address to change resolver data records, keep in mind that it doesn't affect
ProxyConfigResolver which uses permissionless scoped storage.ProxyConfigResolver
ProxyConfig can be used by any 3rd party to assign proxy smart contract which will resolve into content attached to specific CRS record. It's main difference from the rest of resolvers modules, is that it has scoped storage which doesn't require approval by the CRS owner.
Web3 games can use this module methods to store their own metadata for CRS record. Proxy contract can be as simple as definition of specific getter / setter methods (e.g.
tokenURI(uint256), setTokenURI(uint256,string), avatar(uint256), setAvatar(uint256,string)) with local on-chain storage for this data.$3
Get proxy smart contract for
controller and selector. Methods of this contract should be called for final data resolution. When proxy smart contract defines only one getter method, it's recommended to use that method selector (e.g. bytes4(keccak256("tokenURI(uint256)"))). Default proxy contracts should use bytes4(0) selector.$3
Change address of proxy smart contract with specific metadata attached to CRS record by
controller party. Individual proxy contracts can be separated by selector which are either solidity method selectors or by using any other system suitable for controller party. Default proxy contracts should use bytes4(0) selector.ManagedResolver
Is used for the role management associated with a CRS record. It's a good candidate for managing permissions in a system operated by CRS record.
$3
Check if specific
_manager was granted role with _roleSig, signature is generated like bytes4(keccak256("ROLE_NAME")).$3
Grant or revoke role with
_roleSig to _manager address by passing true or false in _active. Role signature is generated like bytes4(keccak256("ROLE_NAME")).KeyHashResolver
Is a more flexible version of
ContenthashResolver, which supports setting separate hashes for different keys. It's useful when you need to attach several external data pieces to one CRS record and manage them separetely. $3
Fetch hash associated with the
_key. Check setKeyHash for details about _key generation and hash decoding.$3
Associate specific
_key with a _keyhash. Key is generated like bytes4(keccak256("KEY_NAME")). Keep in mind that it supports only bytes32 hashes, so you may need to trim static prefixes if IPFS cid is used as a key hash, see examples below:* CID v0:
QmWmyoMoctfbAaiEs2G46gpeUmhqFRDW6KWo64y5r581Vz -> base58.decode() -> 12207d5a99f603f231d53a4f39d1521f98d2e8bb279cf29bebfd0687dc98458e7f89 -> 0x7d5a99f603f231d53a4f39d1521f98d2e8bb279cf29bebfd0687dc98458e7f89.
* CID v1: bafybeibozpulxtpv5nhfa2ue3dcjx23ndh3gwr5vwllk7ptoyfwnfjjr4q -> base32.decode(afybeibozpulxtpv5nhfa2ue3dcjx23ndh3gwr5vwllk7ptoyfwnfjjr4q) -> 017012202ecbe8bbcdf5eb4e506a84d8c49beb6d19f66b47b5b2d6afbe6ec16cd2a531e400000000 -> 0x2ecbe8bbcdf5eb4e506a84d8c49beb6d19f66b47b5b2d6afbe6ec16cd2a531e4NFT interface
Extends ERC721 and Ownable standard contracts. Owner can assign / revoke controllers, change minting fee and update the default resolver contract address.
addController(address _controller)
Add smart contract which can register, renew and use other restricted methods related to CRS management.
removeController(address _controller)
Revoke controller access from smart contract.
setResolver(address _resolver)
Owner can change default resolver smart contract.
setBasenodeResolverSettings(bytes calldata _callData)
Owner can change root domain settings on resolver smart contract.
To change royalties (registration/renew) charged in ERC20 or gas coin, use
for token for gas coin. Individual royalties can be set with forAddress setting, pass address(0) for defaults. callData can be generated in a following way.
`
abi.encodeWithSignature(
"setRoyalties(address,uint256,address,address)",
beneficiary,
amount,
token,
forAddress
)
To change NFT tokenURI proxy, use the following
:
`
abi.encodeWithSignature(
"setProxyConfig(bytes32,address,bytes4,address)",
baseNode,
nftContractAddress,
bytes4(keccak256("tokenURI(uint256,string,string)")), // TOKEN_URI_SELECTOR
proxyContractAddress
)
Getting started
Install packages
$ npm install --dev
Install Hardhat
$ npm install --save-dev hardhat
Launch the local Ethereum client e.g. Ganache or Anvil (recommended):
Integration
Run webpack development server:
Check
for CRS registration UX.Implementation example entrypoints can be found here:
src/index.js and dist/index.html.Testing
Install anvil as local ethereum node as decribed here.
Run it in cli:
anvil;Run tests with truffle:
yarn test.Verification
To try out Etherscan verification, you first need to deploy a contract to an Ethereum network that's supported by Etherscan, such as Rinkeby.
In this project, copy the
.example file to a file named .secret, and then edit it to fill in the details. Enter your Etherscan API key, your Rinkeby node URL (eg from Infura), and the private key of the account which will send the deployment transaction. With a valid .secret file in place, first deploy your contract:`shell
npx hardhat run --network live_goerli scripts/1_deploy_all.js
`Then, copy the deployment address and paste it in to replace
in this command:`shell
npx hardhat verify --network live_goerli DEPLOYED_CONTRACT_ADDRESS ...CONSTRUCTOR_ARGS
`Deployments
Rinkeby
* CRSRegistry deployed to:
* DefaultResolver deployed to:
* ReferenceImplementation deployed to:
* ReferenceController deployed to: Whitelisting private key for ReferenceController:
Goerli
* CRSRegistry deployed to:
* DefaultResolver deployed to:
* ReferenceImplementation deployed to:
* ReferenceController deployed to: Whitelisting private key for ReferenceController:
Polygon
* CRSRegistry deployed to:
* Resolver: