# @decentraweb/resolver

> DNS resolver for Decentraweb

Latest version **2.5.3** (published 2024-05-17) · ISC license · 0 weekly downloads

## Install

```sh
npm install @decentraweb/resolver
pnpm add @decentraweb/resolver
yarn add @decentraweb/resolver
bun add @decentraweb/resolver
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.5.3 |
| Published | 2024-05-17 |
| First published | 2022-09-08 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=16.0.0 |
| Dependencies | 7 |
| Unpacked size | 54.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | krunkosaurus, lytvynenkosv |

## Links

- npm: https://www.npmjs.com/package/@decentraweb/resolver
- Repository: https://github.com/decentraweb/decentrawebjs
- Homepage: https://github.com/decentraweb/decentrawebjs#readme
- Issues: https://github.com/decentraweb/decentrawebjs/issues
- npm.io page: https://npm.io/package/@decentraweb/resolver

## Dependencies (7)

- [bs58](https://npm.io/package/bs58.md) ^5.0.0
- [dotenv](https://npm.io/package/dotenv.md) ^16.0.3
- [ethers](https://npm.io/package/ethers.md) ^5.7.2
- [punycode](https://npm.io/package/punycode.md) ^2.3.0
- [dns-packet](https://npm.io/package/dns-packet.md) ^5.6.0
- [@decentraweb/core](https://npm.io/package/@decentraweb/core.md) ^2.4.2
- [@decentraweb/namekit](https://npm.io/package/@decentraweb/namekit.md) ^2.5.2

## Recent versions

- 2.5.3 (latest) — 2024-05-17
- 3.0.0-alpha.3 (next) — 2024-09-27
- 3.0.0-alpha.1 — 2024-06-07
- 3.0.0-alpha.0 — 2024-06-07
- 2.5.2 — 2024-02-19
- 2.5.1 — 2024-02-19
- 2.5.0 — 2024-01-26
- 2.4.0 — 2024-01-14
- 2.3.0 — 2024-01-10
- 2.2.6 — 2023-12-22
- 2.2.5 — 2023-12-22
- 2.2.4 — 2023-12-22
- 2.2.3 — 2023-11-03
- 2.2.2 — 2023-11-03
- 2.1.0 — 2023-11-01
- … 12 more at https://npm.io/package/@decentraweb/resolver/versions

## README

# Decentraweb DNS Resolver
This package is DNS resolver. It supports resolving DWEB, ENS and ICANN domain names.

**Resolution logic:**
1. If domain ends with `.eth` then it is resolved through ENS.
2. If domain has one of the ICANN TLDs, then it is resolved through regular DNS. 
3. All other domains are resolved with DWEB contracts.

List of ICANN domains can be found at https://data.iana.org/TLD/tlds-alpha-by-domain.txt 

## Resolver types
This package include 3 resolver classes:
1. TCPResolver
2. UDPResolver
3. DOHResolver

TCP and UDP resolvers work with standard DNS protocol which uses binary data format known as 
"wire format". 

`DOHResolver` support 2 types of resolution:
1. `https://{server_address}/dns-query` - standard [RFC 8484](https://datatracker.ietf.org/doc/html/rfc8484) binary format
2. `https://{server_address}/resolve` - JSON API for app developers.

If you are only interested in JSON API, then you can only instantiate `DOHResolver`.

### Binary queries
We use [dns-packet](https://www.npmjs.com/package/dns-packet) package to encode/decode binary DNS packets. It has code
samples for querying DNS over TCP, UPD and DoH https://github.com/mafintosh/dns-packet/tree/master/examples

### JSON API
For app developers it is also possible to use simple JSON API to resolve names.

```shell
curl --location --request GET 'https://{server_address}/resolve?name=frontender.me&type=A'
```

Parameters:
1. `name` - domain name.
2. `type` - record type. Either id or string representation supported. List of types can be found [here](https://en.wikipedia.org/wiki/List_of_DNS_record_types).
Defaults to `A` if not specified.


## Setup
We assume you have node.js v16+ and npm installed. If not please go to https://nodejs.org/ to get latest stable version.

Preparation steps:
1. Create directory to store resolver data. For example `mkdir ~/dweb-resolver`
2. Go to this directory (`cd ~/dweb-resolver`)
3. Install resolver package `npm install @decentraweb/resolver`
4. With editor of your choice create `index.mjs` file with following content:
```javascript 
import { UDPResolver, TCPResolver, DOHResolver } from "@decentraweb/resolver";

/**
 * IP address to listen on. If you want to listen on all interfaces, then use '0.0.0.0'
 */
const addr = '127.0.0.1'
const resolverConfig = {
  blockchain: {
    apiProvider: 'infura', //Supported providers: 'etherscan', 'infura', 'alchemy', 'cloudflare', 'pocket', 'ankr'
    apiKey: '00000000000000000000000000000000', // Your api key
    production: false, // If true, then mainnet and matic networks will be used, otherwise goerli and maticmum
  },
  ipfsGateway: {
    /**
     * IPFS gateway address, domains that have contentHash records will be redirected to this address. Gateway must be 
     * configured to resolve names through this resolver.
     */
    A: '18.177.155.53'
  }
};

const udpServer = new UDPResolver(resolverConfig);

const tcpServer = new TCPResolver(resolverConfig);

const dohServer = new DOHResolver({
  ...resolverConfig,
  cors: true
});

udpServer.listen(53, addr).then(() => {
  console.log(`UDP resolver listening`);
});

tcpServer.listen(53, addr).then(() => {
  console.log(`TCP resolver listening`);
});

dohServer.listen(80).then(() => {
  console.log(`DOH resolver listening`);
});
```
If you would like to use different provider or even your own Ethereum nodes, then config would look like this:
```javascript
import {providers} from 'ethers';
const resolverConfig = {
  blockchain: {
    ethereum: {
      network: 'mainnet', // Or 'goerli'
      provider: new providers.JsonRpcProvider('https://mainnet.infura.io/v3/00000000000000000000000000000000')
    },
    polygon: {
      network: 'matic', // or 'maticmum' if goerli was used for Ethereum
      provider:  new providers.JsonRpcProvider('https://matic.infura.io/v3/00000000000000000000000000000000'),
    },
  },
  ipfsGateway: {
    A: '18.177.155.53'
  }
};
```

## Running
To run resolver execute `node index.mjs` in shell console. You should see following output:
```
UDP resolver listening
DOH resolver listening
TCP resolver listening
```

In another console run:
```shell
dig @127.0.0.1 -p 53 sagan A
```
### Running as a service
There are numerous ways to run Node.js process as a service. We recommend using [pm2](https://pm2.keymetrics.io/).

---
_Source: https://npm.io/package/@decentraweb/resolver · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._