ens-updater
Manage ENS names from the commandline
ens-updater enables automated update of e.g. contentHash records in the Ethereum Name System.
Table of Contents
- Overview
- Security
- Background
- Install
- Usage
- Testing
- Contributing
- Maintainers
- License
- Development support
Overview
Design goals:
- provide an all-purpose cli for managing ENS names
- integrate well in deployment scripts and CI environments
Notable features:
- Get/set ENS name records
- For each operation verifies that the resolver contract of an ENS-name implements the required interface via EIP165 "supportsInterface"
- Show interfaces a resolver implements (command "listInterfaces")
- Includes "--estimateGas" option to check the required gas for a command
- Bash completion support (try command "completion" to set it up)
- Can read input from stdin to support piping with other tools
- Options can be set via json configfile (see config file support)
Security
In order to perform an update of an ENS record, ens-update
needs the private key of the
Ethereum account controlling the ENS name. The private key needs to be provided via environment variable or
through the file .env
in the working directory.
- NEVER share .env file with anybody
- NEVER check .env into version control
- NEVER publish .env in any other way
The private key can be provided either directly or through a mnemonic
Provide the private key
Example contents of .env
:
PRIVATE_KEY=<private key here, without leading 0x>
Provide the mnemonic
Example contents of .env
:
MNEMONIC=<mnemonic phrase here>
By default the first account will be used. If you need to use another account provide the option --accountindex.
Remember - The mnemonic gives full control to all accounts of the according wallet!
Background
For information on the Ethereum Name System see the ENS documentation.
Install
npm install -g @triplespeeder/ens-updater
Usage
The following commands are implemented:
- getInfo for a quick summary
- get/set contenthash
- get/set address record (including eip-2304 Multichain support)
- get/set reverse name records
- get list of interfaces resolver supports
- setup bash completion
PRs to extend functionality are welcome :)
> ens-updater --help
Usage: ens-updater <command> [options]
Commands:
ens-updater.js getInfo <ensname> Get various info about ENS name
ens-updater.js setContenthash <ensname> <contenttype> <contenthash> Set contenthash record
ens-updater.js getContenthash <ensname> Get contenthash record
ens-updater.js clearContenthash <ensname> Clear contenthash record
ens-updater.js setAddress <ensname> <address> [coinname] Set address record
ens-updater.js getAddress <ensname> [coinname] Get address record
ens-updater.js clearAddress <ensname> [coinname] Clear address record
ens-updater.js setReverseName <reverseName> Set reverse name record of calling address
ens-updater.js getReverseName <address> Get reverse name record of address
ens-updater.js clearReverseName Clear reverse name record of calling address
ens-updater.js listInterfaces <ensname> List interfaces resolver supports
ens-updater.js completion generate completion script
Options:
--version Show version number [boolean]
--verbose, -v Verbose output [boolean] [default: false]
--web3 Web3 connection string [string] [required]
--estimateGas Estimate required gas for transactions [boolean] [default: false]
--gasPrice Gas price to set for transaction (unit 'gwei'). Defaults to 10. [number] [default: 10]
--gas Gas to provide for transaction (omit to use automatic calculation) [number]
--dry-run Do not perform any real transactions [boolean] [default: false]
--accountindex, -i Account index. Defaults to 0 [number] [default: 0]
--registryAddress Optional contract address of the ENS Registry. [string]
--help, -h Show help [boolean]
contact: michael@m-bauer.org
github: https://github.com/TripleSpeeder/ens-updater
Example
On Ropsten network, set the contentHash of the name ens-updater.eth
to the IPFS CID QmY7Yh4UquoXHLPFo2XbhXkhBvFoPwmQUSa92pxnxjQuPU
:
> ens-updater setContenthash ens-updater.eth ipfs-ns QmY7Yh4UquoXHLPFo2XbhXkhBvFoPwmQUSa92pxnxjQuPU --web3 http://ropsten.dappnode:8545 --verbose
Setting up web3 & HDWallet provider...
Running on chain ID 3
Verifying ensName owner
Verifying content hash...
Updating contenthash...
Successfully stored new contentHash. Transaction hash: 0x0b8cdb75ff3b514c974ccd0bdef7cc3557bfab934b39caba30c38b88d375d705.
Exiting...
>
Reading values from stdin
Setting the value "stdin" for option contenthash
or address
reads the contenthash/address to set from stdin. This is useful
to build a chain of commands in a deploy script.
For example you can use ipfs-deploy to publish a website to IPFS and directly pipe the CID returned by ipfs-deploy into ens-updater:
> ipfs-deploy -d dappnode | ens-updater setContenthash ens-updater.eth ipfs-ns stdin --web3 http://ropsten.dappnode:8545 --verbose
Getting contenthash from stdin...
Got contenthash: QmY7Yh4UquoXHLPFo2XbhXkhBvFoPwmQUSa92pxnxjQuPU.
Setting up web3 & HDWallet provider...
...
Config file support
All options can be provided through a json config file. The config file can be set with
--config <configfile.json>
option.
Example config file that sets web3 connection string and custom registry address:
{
"web3": "http://127.0.0.1:9545",
"registryAddress": "0x112234455c3a32fd11230c42e7bccd4a84e02010"
}
Usage example:
> ens-updater listInterfaces example.domain.eth --config myconfig.json
Testing
Unittests
Unittests are plain mocha tests located in folder "unitTests". They do not require ganache or other node to run.
Execute tests with npm run test:unit
Integration and end-to-end tests
These tests are implemented with truffle and require a local ganache instance to run. Tests are organized in folders:
-
test/lib/
: Tests of the core functionality from thesrc/lib
folder -
test/middleware/
: Tests of yargs middleware that needs to interact with a live node -
test/end2end/
: Tests of the actual binary. Each test executesens-updater
as a childprocess and verifies the output
To execute the tests:
- Start ganache-cli in a dedicated terminal in deterministic mode:
ganache-cli -d
- Run truffle tests in another terminal:
npm run test:truffle
Contributing
PRs are welcome! Have a look at the open issues or create a new issue if you are missing functionality.
Pull requests should be against the "development" branch.
Commits
Commit messages should follow Conventional Commits guidelines. This is also checked via git hooks and husky.
Structure:
<type> <description>
[optional body]
[optional footer(s)]
Supported types:
- build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
- ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
- docs: Documentation only changes
- feat: A new feature
- fix: A bug fix
- perf: A code change that improves performance
- refactor: A code change that neither fixes a bug nor adds a feature
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- test: Adding missing tests or correcting existing tests
Maintainers
Development support
If you like this project consider contributing to the gitcoin grant: https://gitcoin.co/grants/218/ens-updater.
If you prefer direct donations please use: ens-updater.eth (0x8651Cf790fc894512a726A402C9CAAA3687628f0)
License
MIT
© 2019 - 2020 Michael Bauer