# @cndllabs/ui

> UI components and reusable code

Latest version **3.4.8** (published 2022-06-24) · ISC license · 0 weekly downloads

## Install

```sh
npm install @cndllabs/ui
pnpm add @cndllabs/ui
yarn add @cndllabs/ui
bun add @cndllabs/ui
```

## Health

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

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.4.8 |
| Published | 2022-06-24 |
| First published | 2022-06-09 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 20 |
| Unpacked size | 209.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | safahi |

## Links

- npm: https://www.npmjs.com/package/@cndllabs/ui
- npm.io page: https://npm.io/package/@cndllabs/ui

## Dependencies (20)

- [bs58](https://npm.io/package/bs58.md) ^4.0.1
- [bech32](https://npm.io/package/bech32.md) ^1.1.3
- [ethers](https://npm.io/package/ethers.md) ^5.6.2
- [js-sha3](https://npm.io/package/js-sha3.md) ^0.8.0
- [dns-packet](https://npm.io/package/dns-packet.md) ^5.2.1
- [base58check](https://npm.io/package/base58check.md) ^2.0.0
- [cross-fetch](https://npm.io/package/cross-fetch.md) ^3.0.2
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.4.4
- [@0xproject/utils](https://npm.io/package/@0xproject/utils.md) ^2.0.2
- [@ensdomains/mock](https://npm.io/package/@ensdomains/mock.md) npm:ensdomains-mock@^2.1.50
- [@ensdomains/contracts](https://npm.io/package/@ensdomains/contracts.md) ^0.0.1
- [@ensdomains/dnsprovejs](https://npm.io/package/@ensdomains/dnsprovejs.md) ^0.4.1
- [@cndllabs/cns-contracts](https://npm.io/package/@cndllabs/cns-contracts.md) 0.2.5
- [@ensdomains/content-hash](https://npm.io/package/@ensdomains/content-hash.md) ^2.5.7
- [@ethvault/iframe-provider](https://npm.io/package/@ethvault/iframe-provider.md) 0.1.9
- [@ensdomains/dnssecoraclejs](https://npm.io/package/@ensdomains/dnssecoraclejs.md) ^0.2.7
- [@ensdomains/address-encoder](https://npm.io/package/@ensdomains/address-encoder.md) ^0.2.17
- [@ensdomains/eth-ens-namehash](https://npm.io/package/@ensdomains/eth-ens-namehash.md) ^2.0.15
- [@ensdomains/dnssecoraclejs-017](https://npm.io/package/@ensdomains/dnssecoraclejs-017.md) npm:@ensdomains/dnssecoraclejs@0.1.7
- [@babel/plugin-proposal-class-properties](https://npm.io/package/@babel/plugin-proposal-class-properties.md) ^7.8.3

## Recent versions

- 3.4.8 (latest) — 2022-06-24
- 3.4.7 — 2022-06-24
- 3.4.6 — 2022-06-24
- 3.4.5 — 2022-06-15
- 3.4.2 — 2022-06-09

## README

# Reusable functions and components for the CNS apps

Most functions in this library are async functions and therefore return promises which can be awaited or chained with `.then`.

## Contents

- Registry and Resolvers

  - [setupCNS()](#async-function-setupCNSoptions-void)
  - [getOwner()](#async-function-getownername-address)
  - [getResolver()](#async-function-getresolvername-address)
  - [getTTL()](#async-function-getttlname-number)
  - [getOwnerWithLabelhash()](#async-function-getownerwithlabelhashlabelhash-nodehash-address)
  - [getResolverWithLabelhash()](#async-function-getresolverwithlabelhashlabelhash-nodehash-address)
  - [getAddress()](#async-function-getaddressname-address)
  - [getAddr()](#async-function-getaddrname-key-address)
  - [getContent()](#async-function-getcontentname-contenthash)
  - [getText()](#async-function-gettextname-key-value)
  - [getName()](#async-function-getnameaddress-name)
  - [getSubdomains()](#async-function-getsubfomains-address)
  - [setSubnodeOwner()](#async-function-setsubnodeownername-newowner-transactionresponse)
  - [setSubnodeRecord()](#async-function-setsubnoderecordname-newowner-resolver-transactionresponse)
  - [setResolver()](#async-function-setresolvername-resolver-transactionresponse)
  - [setAddress()](#async-function-setaddressname-address-transactionresponse)
  - [setAddr()](#async-function-setaddrname-key-address-transactionresponse)
  - [setContent() DEPRECATED](#async-function-setcontentname-content-transactionresponse-deprecated)
  - [setContenthash()](#async-function-setcontenthashname-content-transactionresponse)
  - [setText()](#async-function-settextname-key-value-transactionresponse)
  - [checkSubdomain()](#async-function-checksubdomainlabel-name-boolean)
  - [createSubdomain()](#async-function-createsubdomainlabel-name-transactionresponse)
  - [deleteSubdomain()](#async-function-deletesubdomainlabel-name-transactionresponse)
  - [claimAndSetReverseRecord()](#async-function-claimandsetreverserecordnamename-transactionresponse)
  - [setReverseRecord](#async-function-setreverserecordnamename-transactionresponse)
  - [getDomainDetails](#async-function-getdomaindetailsname-transactionresponse)
  - [getSubdomains](#async-function-getsubdomainsname-arraysubdomain)

- [Transaction Response](#transaction-response)

## Setup

Setup for the library is done by calling the `setupCNS` function. It can be optionally provided with a customProvider and an CNS address. Generally you won't need this unless you are running ganache.

It will return an object with the registrar and cns object. The cns object will deal with name resolution, reverse records and dealing with the registry. The registrar object has functions to interact the permanent registrar, legacy auction registrar and test registrar (just on test net)

```js
import { setupCNS } from '@cndllabs/ui'

window.addEventListener('load', async () => {
  const { registrar, cns } = await setupCNS()
  const owner = await cns.getOwner('resolver.eth')
  // will instantiate with window.web3/window.ethereum if found, read-only if not.
  // Once setup has finished you can now call functions off the library
})
```

## API

### `async function setupCNS(options): void`

setupCNS must be called before anything other function in this library. We recommend calling it in a window.load event to make sure that your web3 object has loaded. You can provide a custom provider yourself, but by default it will look for `window.web3` or `window.ethereum` if you do not give it a provider. We use the custom provider when we need to run automated tests with ganache. You can also it pass it the registry address, but by default it will derive the network you are on and instantiate CNS using that network's registry. You only need to provider it with an cns address if you are on a private network.

#### Arguments

```
options (object): {
  customProvider (object): Provider object from web3 (optional)
  cnsAddress (String): Address of the CNS registry (optional)
}
```

#### Example

```js
import { setupCNS } from '@cndllabs/ui'

window.addEventListener('load', async () => {
  const { cns, registrar } = await setupCNS()
})
```

### `async function getOwner(name): Address`

#### Arguments

name (String): An CNS name (e.g: vitalik.eth)

#### Returns

owner (address): Ethereum address of the owner on the registry

#### Example

```js
const name = 'vitalik.eth'
const owner = await cns.getOwner(name)
// 0x123...
```

### `async function getResolver(name): Address`

#### Arguments

name (String): An CNS name (e.g: vitalik.eth)

#### Returns

owner (address): Ethereum address of the resolver contract

#### Example

```js
import cns from 'cns'
const owner = await cns.getResolver('vitalik.eth')
// 0x123...
```

### `async function getTTL(name): Number`

#### Arguments

name (String): An CNS name (e.g: vitalik.eth)

#### Returns

ttl (number): Returns the caching time-to-live of the name specified by node. Systems that wish to cache information about a name, including ownership, resolver address, and records, should respect this value. If TTL is zero, new data should be fetched on each query.

#### Example

```js
import cns from 'cns'
const ttl = await cns.getTTL('resolver.eth')
// 12345
```

### `async function getOwnerWithLabelHash(labelHash, nodeHash): Address`

#### Arguments

labelHash (String): Sha3 hash of the label e.g vitalik (vitalik.eth)
nodeHash (String): Namehash of the rest of the name (minus the label) e.g eth (vitalik.eth)

#### Returns

owner (address): Ethereum address of the resolver contract

#### Example

```js
import cns from 'cns'
const owner = await cns.getOwnerWithLabelHash(labelHash, nodeHash)
// 0x123...
```

### `async function getResolverWithLabelHash(labelHash, nodeHash): Address`

#### Arguments

labelHash (String): Hash of the label e.g vitalik (vitalik.eth)
nodeHash (String): Hash of the rest of the name (minus the library) e.g eth (vitalik.eth)

#### Returns

resolver (address): Ethereum address of the resolver contract

#### Example

```js
const resolver = await cns.getResolverWithLabelHash(labelHash, nodeHash)
// 0x123...
```

### `async function getAddress(name): Address`

This function will call the resolver to get the address, if it cannot find a resolver, it will return `0x000...` as a fallback

#### Arguments

name (String): An CNS name (e.g: vitalik.eth)

#### Returns

address (address): An Ethereum address that was set on the resolver

#### Example

```js
const addr = await cns.getAddress('vitalik.eth')
// 0x123...
```

### `async function getAddr(name, key): Address`

This function will call the resolver to get the address based on name and coin type of various blockchains, if it cannot find a resolver, it will return `0x000...` as a fallback

#### Arguments

name (String): An CNS name (e.g: vitalik.eth)
key (String): CoinType (e.g: ETH, EOS, ETC, specified in [address-encoder](https://github.com/ensdomains/address-encoder#supported-cryptocurrencies))

#### Returns

address (address): A blockchain address that was set on the resolver

#### Example

```js
const addr = await cns.getAddress('vitalik.eth', 'ETC')
// 0x123...
```

### `async function getContent(name): Contenthash`

This function will call the resolver to get the contentHash, if it cannot find a resolver, it will return `0x000...` as a fallback. Otherwise it will return a contenthash in text format, as defined by [EIP1577](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1577.md).

#### Arguments

name (String): An CNS name (e.g: vitalik.eth)

#### Returns

contentHash (String): A content hash String for IPFS or swarm

#### Example

```js
const content = await cns.getContent('vitalik.eth')
// ipfs://Qsxz...
```

### `async function getText(name, key): Value`

This function gets the reverse record of an address.

#### Arguments

name (String): CNS name
key (String): Any keys. Standard values for key

#### Returns

value (String): A value

#### Example

```js
const name = await cns.getText('vitalik.eth', 'url')
// https://vitalik.ca/
```

### `async function getName(address): Name`

This function gets the reverse record of an address.

#### Arguments

address (String): An Ethereum address

#### Returns

name (String): An CNS name

#### Example

```js
const name = await cns.getName('0x123abc...')
// vitalik.eth
```

### `async function getSubdomains(): [Address]`

This function gets the reverse record of an address.

#### Arguments

name (String): An CNS name

#### Returns

addresses (Array): An CNS name

#### Example

```js
const name = await cns.getSubdomains('vitalik.eth')
// ['0x123','0x123']
```

### `async function setOwner(name, newOwner): TransactionResponse`

#### Arguments

name (String): An CNS name
newOwner (String): An Ethereum address or contract

#### Returns

transaction (object): [Transaction Response Object](#transaction-response)

#### Example

```js
const tx = await cns.setOwner('vitalik.eth', '0x123abc...')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined
```

### `async function setSubnodeOwner(name, newOwner): TransactionResponse`

Can only be called by the controller of the parent name.

#### Arguments

name (String): An CNS name
newOwner (String): An Ethereum address or contract

#### Returns

transaction (object): [Transaction Response Object](#transaction-response)

#### Example

```js
const tx = await cns.setSubnodeOwner('sub.vitalik.eth', '0x123abc')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined
```

### `async function setSubnodeRecord(name, newOwner, resolver): TransactionResponse`

Sets the record for a subnode. Can only be called by the controller of the parent name.

#### Arguments

name (String): An CNS name
newOwner (String): An Ethereum address or contract
resolver (Address): Resolver 

#### Returns

transaction (object): [Transaction Response Object](#transaction-response)

#### Example

```js
const tx = await cns.setSubnodeRecord(
  'subnode.resolver.eth',
  '0x134',
  '0x123'
)

console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined
```

### `async function setResolver(name, resolver): TransactionResponse`

Can only be called by the controller of the name.

#### Arguments

name (String): An CNS name
resolver (String): An CNS [resolver contract](https://github.com/ensdomains/resolvers)

#### Returns

transaction (object): [Transaction Response Object](#transaction-response)

#### Example

```js
const tx = await cns.setResolver('vitalik.eth', '0x123abc')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined
```

### `async function setAddress(name, address): TransactionResponse`

Can only be called by the controller of the name.

#### Arguments

name (String): An CNS name
address (String): An Ethereum address

#### Returns

transaction (object): [Transaction Response Object](#transaction-response)

#### Example

```js
const tx = await cns.setAddress('vitalik.eth', '0x123abc')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined
```

### `async function setAddr(name, key, address): TransactionResponse`

Can only be called by the controller of the name.

#### Arguments

name (String): An CNS name
key (String): CoinType (e.g: ETH, EOS, ETC, specified in [address-encoder](https://github.com/ensdomains/address-encoder#supported-cryptocurrencies))
address (String): An Ethereum address

#### Returns

transaction (object): [Transaction Response Object](#transaction-response)

#### Example

```js
const tx = await cns.setAddr(
  'vitalik.eth',
  'ETH',
  '0x0000000000000000000000000000000000012345'
)

console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined
```

### `async function setContent(name, content): TransactionResponse (DEPRECATED)`

Can only be called by the controller of the name.

This function has been deprecated in favour of `setContenthash` which uses [EIP1577](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1577.md)

#### Arguments

name (String): An CNS name
content (String): A content hash

#### Returns

transaction (object): [Transaction Response Object](#transaction-response)

#### Example

```js
const tx = await cns.setContent('vitalik.eth', '0x123abc')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined
```

### `async function setContenthash(name, content): TransactionResponse`

Can only be called by the controller of the name.

#### Arguments

name (String): An CNS name
contenthash (String): A content hash defined by [EIP1577](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1577.md)

#### Returns

transaction (object): [Transaction Response Object](#transaction-response)

#### Example

```js
const tx = await cns.setContent('vitalik.eth', '0x123abc')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined
```


### `async function setText(name, key, value): TransactionResponse`

Sets text metadata for node with the unique key key to value, overwriting anything previously stored for node and key. To clear a text field, set it to the empty string.

#### Arguments

name (String): An CNS name
key  (String): key
value (String): Value
#### Returns

transaction (object): [Transaction Response Object](#transaction-response)

#### Example

```js
const tx = await cns.setText('vitalik.eth', 'url', 'vitalik.ca')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined
```

### `async function createSubdomain(name): TransactionResponse`

Can only be called by the controller of the name. This is a simplified version of `setSubnodeOwner` which it uses underneath to create a subdomain. It will automatically set the owner to the parent's names owner. If you call this function on an existing subdomain, it will change its owner to the current parent owner.

#### Arguments

name (String): An CNS name (sub.vitalik.eth)

#### Returns

transaction (object): [Transaction Response Object](#transaction-response)

#### Example

```js
const tx = await cns.createSubdomain('sub', 'vitalik.eth')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined
```

### `async function deleteSubdomain(label, name): TransactionResponse`

Can only be called by the controller of the name. This function will set the controller to `0x000...` and if it has a resolver, it will set the resolver `0x000...`, which will be a second transaction. Alternatively you can manually call `setSubnodeOwner` and set the controller to `0x000...`

#### Arguments

label (String): CNS Label e.g: sub (sub.vitalik.eth)
name (String): An CNS name

#### Returns

transaction (object): [Transaction Response Object](#transaction-response)

#### Example

```js
const tx = await cns.deleteSubdomain('sub', 'vitalik.eth')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined
```

### `async function claimAndSetReverseRecordName(name): TransactionResponse`

This function will claim your Ethereum address on the reverse registrar, setup the reverse resolver and setup your name on the resolver all in one transaction. It can also be used to change your reverse record name to something else.

#### Arguments

name (String): An CNS name

#### Returns

transaction (object): [Transaction Response Object](#transaction-response)

#### Example

```js
const tx = await cns.claimAndSetReverseRecordName('vitalik.eth')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined
```

### `async function setReverseRecordName(name): TransactionResponse`

This function will set your reverse record name given that a resolver is already present on your ethereum address reverse name e.g. `123456abcdef.addr.reverse`. This can be useful if you don't want to use `claimAndSetReverseRecordName` to setup the default reverse registrar

#### Arguments

name (String): An CNS name

#### Returns

transaction (object): [Transaction Response Object](#transaction-response)

#### Example

```js
const tx = await cns.setReverseRecordName('vitalik.eth')
console.log(tx.hash)
// 0x123456...
const receipt = await tx.wait() // Wait for transaction to be mined
// Transaction has been mined
```

### `async function getDomainDetails(name): DomainDetails`

This is a helper function to get all the details for a particular domain.

#### Arguments

name (String): An CNS name

#### Returns

```
DomainDetails (object): {
  name (String): CNS name
  label (String): label of the name
  labelhash (String): labelhash of the name
  owner (String): Address of the controller of the CNS name
  resolver (String): CNS resolver contract
  addr (String): Address the CNS name resolves to
  content (String): Contenthash the CNS name resolves to
}
```

#### Example

```js
const domainDetails = await cns.getDomainDetails('vitalik.eth')
console.log(domainDetails)
/* 
  {
    name: "vitalik.eth",
    label: "vitalik",
    labelhash: "0x123456abc...",
    owner: "0x123abcdef...",
    resolver: "0x1234abdef...",
    addr: "0xabcdef1234...",
    content: "bzz://Qra123..."
  }
*/
```

### `async function getSubdomains(name): Array<Subdomain>`

This is a helper function to get all the subdomains for a name. Internally it will search for events for the `NewOwner` and filter out duplicates.

#### Arguments

name (String): An CNS name

#### Returns

```
Subdomains (Array<Subdomain>): {
  name (String): CNS name
  label (String): label of the name
  labelhash: labelhash of the name
  owner (String): Address of the controller of the CNS name
  decrypted (boolean): Whether the label is known or not
}
```

#### Example

```js
const subdomains = await cns.getSubdomains('vitalik.eth')
console.log(subdomains)
/* 
  [{
    name: "vitalik.eth",
    label: "vitalik",
    labelhash: "0x123456abc...",
    owner: "0x123abcdef...",
    decrypted: true
  }, ...]
*/
```

## Transaction Response

The transaction response object gets returned by the promise of all state modifying functions of the library. The most important properties is the `wait` function which can be called by the initial response, before the transaction has been mined. You can await this promise and it will give you the transaction receipt. The transaction receipt, is the same as the transaction response object, except is has a `blockHash`, `blockNumber` and `timestamp` of the block the transaction has been included in.

```js
{
    // Only available for unmined transactions
    wait: function(){}, //this function is to wait for the transaction to be mined
    // Only available for mined transactions
    blockHash: "0x7f20ef60e9f91896b7ebb0962a18b8defb5e9074e62e1b6cde992648fe78794b",
    blockNumber: 3346463,
    timestamp: 1489440489,

    // Exactly one of these will be present (send vs. deploy contract)
    // They will always be a properly formatted checksum address
    creates: null,
    to: "0xc149Be1bcDFa69a94384b46A1F91350E5f81c1AB",

    // The transaction hash
    hash: "0xf517872f3c466c2e1520e35ad943d833fdca5a6739cfea9e686c4c1b3ab1022e",

    // See above "Transaction Requests" for details
    data: "0x",
    from: "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8",
    gasLimit: utils.bigNumberify("90000"),
    gasPrice: utils.bigNumberify("21488430592"),
    nonce: 0,
    value: utils.parseEther(1.0017071732629267),

    // The chain ID; 0 indicates replay-attack vulnerable
    // (eg. 1 = Homestead mainnet, 3 = Ropsten testnet)
    chainId: 1,

    // The signature of the transaction (TestRPC may fail to include these)
    r: "0x5b13ef45ce3faf69d1f40f9d15b0070cc9e2c92f3df79ad46d5b3226d7f3d1e8",
    s: "0x535236e497c59e3fba93b78e124305c7c9b20db0f8531b015066725e4bb31de6",
    v: 37,

    // The raw transaction (TestRPC may be missing this)
    raw: "0xf87083154262850500cf6e0083015f9094c149be1bcdfa69a94384b46a1f913" +
           "50e5f81c1ab880de6c75de74c236c8025a05b13ef45ce3faf69d1f40f9d15b0" +
           "070cc9e2c92f3df79ad46d5b3226d7f3d1e8a0535236e497c59e3fba93b78e1" +
           "24305c7c9b20db0f8531b015066725e4bb31de6",
}
```

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