@ensdomains/ensjs 2.0.0 → 3.0.0-alpha.1

package/README.md

@@ -1,160 +1,714 @@
-# ENS.js V2
+# ![ENSjs](https://user-images.githubusercontent.com/11844316/161689061-98ea01ee-b119-40ac-a512-5370eb8b4107.svg)
 
-This is the rewrite of `ensjs`. If you are looking for the previous version, look for [ethereum-ens](https://www.npmjs.com/package/ethereum-ens)
+The ultimate ENS javascript library, with [ethers.js](https://github.com/ethers-io/ethers.js) under the hood.
 
-## Overview of the API
+## NOTE!!!
 
-### Setup
+ENSjs v3 is currently in the early development stage, meaning that the APIs are subject to change.
+We also use undeployed contracts under the hood, so this **will not** work on any mainnet/testnet where the contracts are not deployed.
 
-```
-import ENS, { getEnsAddress } from '@ensdomains/ensjs'
+Given the current development status, we're actively seeking feedback so feel free to create an issue or PR if you notice something!
+
+## Features
 
+- Dynamically load **everything**
+- Super fast response times (1 call for most RPC calls)
+- Easy call batchability
+- Written in TypeScript
+- Supports the most cutting edge ENS features
+- - More
 
+## Installation
 
-const ens = new ENS({ provider, ensAddress: getEnsAddress('1') })
+Install @ensdomains/ensjs, alongside [ethers](https://github.com/ethers-io/ethers.js).
 
-ens.name('resolver.eth').getAddress() // 0x123
+```sh
+npm install @ensdomains/ensjs ethers
 ```
 
-### exports
+## Getting Started
 
-```
-default - ENS
-getEnsAddress
-getResolverContract
-getENSContract
-namehash
-labelhash
-```
+All that's needed to get started is an ethers provider instance.
+Once you create a new ENS instance, you can pass it in using setProvider.
+
+```js
+import { ENS } from '@ensdomains/ensjs'
+import { ethers } from 'ethers'
 
-### ENS Interface
+const provider = new ethers.providers.JsonRpcProvider(providerUrl)
 
+const ENSInstance = new ENS()
+await ENSInstance.setProvider(provider)
 ```
-name(name: String) => Name
+
+## Batching Calls
+
+The batch function is a large part of this library, and there are plenty of situations where you might want to use it.
+**Note that only functions with the `GeneratedRawFunction` type can be batched together.**
+
+```js
+/* Batch functions can be called like so, with the function as the first item in an array, with the following items being the function's arguments */
+const batched = await batch(
+  ENSInstance.getText.batch('test.eth', 'foo'),
+  ENSInstance.getAddr.batch('test.eth'),
+  ENSInstance.getOwner.batch('test.eth'),
+)
+
+/* The response is formatted like so:
+  [
+    response1,
+    response2,
+    response3,
+    ...etc,
+  ]
+*/
 ```
 
-Returns a Name Object, that allows you to make record queries.
+## Using Custom Graph Node URIs
 
-```
-resolver(address: EthereumAddress) => Resolver
-```
+If you want to use your own graph-node URI, such as a local graph-node URI, you can pass it through when creating a new ENS instance.
+Alternatively, if you don't want to use The Graph at all you can pass through `null`.
 
-Returns a Resolver Object, allowing you to query names from this specific resolver. Most useful when querying a different resolver that is different than is currently recorded on the registry. E.g. migrating to a new resolver
+```js
+import { ENS } from '@ensdomains/ensjs'
 
-```
-async getName(address: EthereumAddress) => Promise<Name>
+/* If you want to use a custom URI */
+const ENSInstance = new ENS({
+  graphURI: 'http://localhost:8000/subgraphs/name/graphprotocol/ens',
+})
+
+/* If you want to disable The Graph queries */
+const ENSInstance = new ENS({ graphURI: null })
 ```
 
-Returns the reverse record for a particular Ethereum address.
+## Single-use Providers
 
-```
-async setReverseRecord(name: Name) => Promise<EthersTxObject>
-```
+If you want to use a specific provider to make a single call occasionally, you can easily do so.
 
-Sets the reverse record for the current Ethereum address
+```js
+import { ENS } from '@ensdomains/ensjs'
 
-### Name Interface
+const ENSInstance = new ENS()
 
-```ts
-async getOwner() => Promise<EthereumAddress>
+const callWithProvider = await ENSInstance.withProvider(otherProvider).getText(
+  'test.eth',
+  'foo',
+)
 ```
 
-Returns the owner/controller for the current ENS name.
+## Profiles
+
+You can fetch almost all information about an ENS name (or address) using getProfile.
+If an address is used as the first argument, it will fetch the primary name and give the same response as a name would.
+It will automatically get all the records for a name, as well as get the resolver address for the name.
+Specific records can also be used as an input, if you only want to get certain ones. If an address is used as an input alongside this,
+you also save 1 RPC call.
+
+**NOTE:**  
+The profile function will always request an ETH addr record.
+For names, this means the address will always at the top level of the returned object.
+For addresses, this means the "match" property (a boolean value for matching reverse/forward resolution) will always be at the top level of the returned object.
+
+```js
+/* Normal profile fetching */
+const profile = await ENSInstance.getProfile('test.eth')
+
+/* Profile fetching from an address */
+const profile = await ENSInstance.getProfile(
+  '0xeefB13C7D42eFCc655E528dA6d6F7bBcf9A2251d',
+)
+
+/* Get all records of a specific type (or multiple) */
+const profile = await ENSInstance.getProfile('test.eth', {
+  texts: true,
+  coinTypes: true,
+  contentHash: true,
+})
+
+/* Get specific records */
+const profile = await ENSInstance.getProfile('test.eth', {
+  texts: ['foo'],
+  coinTypes: ['ETH'],
+})
+```
 
-```ts
-async setOwner(address: EthereumAddress) => Promise<Ethers>
+Returns:
+
+```typescript
+type RecordItem = {
+  key: string | number
+  type: 'addr' | 'text' | 'contentHash'
+  coin?: string
+  addr?: string
+  value?: string
+}
+
+type ProfileReturn = {
+  address?: string // ONLY RETURNED AT TOP-LEVEL FOR NAME QUERIES
+  name?: string // ONLY RETURNED AT TOP-LEVEL FOR ADDRESS QUERIES
+  records: {
+    contentHash?: ContentHashObject | null
+    texts?: RecordItem[]
+    coinTypes?: RecordItem[]
+  }
+  resolverAddress: string
+}
 ```
 
-Sets the owner/controller for the current ENS name.
+## Name History
 
-```ts
-async getResolver() => Promise<EthereumAddress>
-```
+Getting the history for a name is very simple and can be done in two ways.
+Not all data can be immediately fetched for the history of an ENS name, which is why there is multiple methods for doing so.
+Text records do not contain the string value of the changed record, only the key. The value needs to be derived from fetching
+the individual transaction hash. This can potentially be very slow if the name has a long history.
 
-Returns the resolver for the current ENS name.
+```js
+/* Normal Fetching, requires a second function for more details */
+const history = await ENSInstance.getHistory('test.eth')
 
-```ts
-async setResolver(address: EthereumAddress) => Promise<EthereumAddress>
+/* Details helper for history */
+/* You'll need to implement custom logic to get the index if you want to use that parameter, it's not currently done in the function */
+const detail = await ENSInstance.getHistoryDetailForTransactionHash(
+  transactionHash,
+  optionalIndex,
+)
+
+/* Fetching with all details upfront */
+const historyWithDetail = await ENSInstance.getHistoryWithDetail('test.eth')
 ```
 
-Sets the resolver for the current ENS name.
+## Ownership Levels
 
-```ts
-async getTTL() => Promise<Number>
-```
+The `getOwner` function returns not only an owner (and potentially a registrant), but also a ownershipLevel value.
+This value essentially means the contract for the "real owner" of any given name. In most cases it means the NFT contract
+of the name, but if there is no NFT then it's just the registry. This value is useful for input into the `transferName`
+function, where a contract needs to be specified.
 
-Returns the TTL for the current ENS name.
+## Wrapping Names
 
-```ts
-async getAddress(coinId: String) => Promise<EthereumAddress>
-```
+Wrapping names is very simple, you can wrap any name from the same function, with the exact contract to use being inferred.
+You can specify both the fuses and resolver address to use with the wrapped name, but it's entirely optional.
 
-Returns the address for the current ENS name for the coinId provided.
+```js
+/* wrap a .eth name */
+const tx = await ENSInstance.wrapName(
+  'test.eth', // Name to wrap
+  '0xeefB13C7D42eFCc655E528dA6d6F7bBcf9A2251d', // New owner of wrapped name
+)
 
-```ts
-async setAddress(coinId: String, address: EthereumAddress) => Promise<EthersTxObject>
+/* wrap any other name (e.g. a subname) */
+const tx = await ENSInstance.wrapName(
+  'sub.test.eth',
+  '0xeefB13C7D42eFCc655E528dA6d6F7bBcf9A2251d',
+)
 ```
 
-Sets the address for the current ENS name for the coinId provided.
+## Write Transaction Options
 
-```ts
-async getContent() => Promise<ContentHash>
-```
+Currently, some write functions have an `options` argument. While this may expand over time,
+it currently just allows you to pass an address or index for an account array to ethers for specifying the signer of the transaction.
 
-Returns the contentHash for the current ENS name.
+## Internal Structure
 
-```ts
-async setContenthash(content: ContentHash) => Promise<EthersTxObject>
-```
+### Raw Functions
 
-Sets the contentHash for the current ENS name.
+Raw functions are a crucial part of how ENSjs works. In the function file itself
+a `raw` and `decode` function both need to be defined, with the export being an object with those properties.
+This allows for the encoding and decoding of contract calls to be split, meaning that multiple calls can be batched together.
+For calling a raw function by itself, the raw and decode functions are stitched together with a provider call. This is done
+using `importGenerator` which is explained below.
 
-```ts
-async getText(key: String) => Promise<String>
-```
+### importGenerator
 
-Returns the text record for a given key for the current ENS name.
+The importGenerator function generates a wrapped function for any given input.
+The result of the wrapped function obfuscates the processing that ENSjs does, and exposes a cleaner API to the user/developer.
+The reason we do this is to:
 
-```ts
-async setText(key: String, recordValue: String) => Promise<EthersTxObject>
-```
+1. Pass through all the required variables for the function
+2. Split individual functions from the main class
+3. Dynamically load functions and their dependencies
+4. Allow each function's dependencies to be imported regularly
+5. Remove duplicate code
+6. Make it easier to isolate errors
+7. Stitch `raw` and `decode` functions together
 
-Sets the text record for a given key for the current ENS name.
+### ContractManager
 
-```ts
-async setSubnodeOwner(label: String, newOwner: EthereumAddress) => Promise<EthersTxObject>
-```
+The contract manager is where all the contracts are dynamically loaded in and resolved based on the network.
+A new instance of ContractManager is created every time you switch providers.
 
-Sets the subnode owner for a subdomain of the current ENS name.
+### GqlManager
 
-```ts
-async setSubnodeRecord(label: String, newOwner: EthereumAddress, resolver: EthereumAddress, ttl: ?Number) => Promise<EthersTxObject>
-```
+The GQL manager is used as to separate the reliance of ENSjs from GQL.
+It only loads in GQL when it is needed, or not at all if specified in the constructor of the ENS class.
+Very simply, it just exposes the core functions needed for ENSjs which can then be accessed.
 
-Sets the subnode owner, resolver, ttl for a subdomain of the current ENS name in one transaction.
+### initialProvider
 
-```ts
- async createSubdomain(label: String) => Promise<EthersTxObject>
-```
+The `initialProvider`, and similarly `checkInitialProvider` are used when creating single-use class instances with `withProvider`.
+It allows `withProvider` to act as a new ENS instance without having to await a promise, which simplifies the API.
+`checkInitialProvider` is run on every function call given that it's extremely lightweight.
 
-Creates a subdomain for the current ENS name. Automatically sets the owner to the signing account.
+## Individual Functions
 
-```ts
-async deleteSubdomain(label: String) => Promise<EthersTxObject>
-```
+### getFuses
 
-Deletes a subdomain for the current ENS name. Automatically sets the owner to "0x0..."
+Gets the fuses for a specified wrapped name.
 
-## Resolver Interface
+Input:
 
-```ts
-address
-```
+- `name`: string
+  - Target name
 
-Static property that returns current resolver address
+Output:
 
-```ts
-name(name) => Name
-```
+- `fuseObj`: object
+  - Decoded known fuses
+- `vulnerability`: string
+  - Vulnerability for name
+  - Will be "Safe" if no vulnerability
+- `vulnerableNode`: string | null
+  - Node that is vulnerable in chain
+- `rawFuses`: BigNumber
+  - Unformatted fuse result
+
+### getHistory
+
+Gets the history for a specified name.
+
+Input:
+
+- `name`: string
+  - Target name
+
+Output:
+
+- `domain`: array
+  - Domain event item
+- `registration`: array
+  - Registration event item
+- `resolver`: array
+  - Resolver event item
+
+### getHistoryWithDetail
+
+Gets the history for a specified name with details.
+
+Input:
+
+- `name`: string
+  - Target name
+
+Output:
+
+- `domain`: array
+  - Domain event item
+- `registration`: array
+  - Registration event item
+- `resolver`: array
+  - Resolver event item
+
+### getHistoryDetailForTransactionHash
+
+Gets the history details for a specified transaction hash.
+
+Input:
+
+- `hash`: string
+  - Target transaction hash
+- `indexInTransaction`: number?
+  - Index of transaction out of same transaction type
+
+Output:
+
+- object | array
+  - `key`: string
+    - Key for detail
+  - `value`: string
+    - Value for detail
+
+### getName
+
+Gets the primary name for a specified address.
+
+Input:
+
+- `address`: string
+  - Target address
+
+Output:
+
+- `name`: string | null
+  - Resolved name
+- `match`: boolean
+  - Forward resolved match check value
+
+### getOwner
+
+Gets the owner of a specified name. See _ownership levels_ for more details about the output.
+
+Input:
+
+- `name`: string
+  - Target name
+
+Output:
+
+- `owner`: string
+  - Controller of records for name
+- `registrant`: string?
+  - NFT Owner
+- `ownershipLevel`: string
+  - Level at which the ownership data is being read
+
+### getProfile
+
+Gets the profile of a specified name or address, or just certain records if specified.
+
+Input:
+
+- `nameOrAddress`: string
+  - Target name or address
+- `options`: object?
+  - `contentHash`: boolean?
+  - `texts`: boolean? | string[]?
+    - Array of keys, or true for all keys
+  - `coinTypes`: boolean? | string[]?
+    - Array of keys, or true for all keys
+
+Output:
+
+- `resolverAddress`: string
+  - Address of resolver
+- `records`: object
+  - matching records from input
+  - `contentHash`: object? | null?
+    - Decoded content hash
+  - `texts`: array?
+    - `key`: string
+    - `value`: string
+  - `coinTypes`: array?
+    - `key`: number
+    - `coin`: string
+      - Coin name
+    - `value`: string
+      - Decoded address
+- `name`: string?
+  - _Only applicable for address inputs_
+  - Resolved name
+- `address`: string?
+  - _Only applicable for name inputs_
+  - Resolved address
+- `match`: boolean?
+  - _Only applicable for address inputs_
+  - Forward resolved match check value
+
+### getRecords
+
+Gets all the records of a specified name, or just certain records if specified.
+
+Input:
+
+- `name`: string
+- `options`: object?
+  - `contentHash`: boolean?
+  - `texts`: boolean? | string[]?
+    - Array of keys, or true for all keys
+  - `coinTypes`: boolean? | string[]?
+    - Array of keys, or true for all keys
+
+Output: **see getProfile**
+
+### getResolver
+
+Gets the resolver for a specified name.
+
+Input:
+
+- `name`: string
+  - Target name
+
+Output:
+
+- string
+  - Resolver address
+
+### getContentHash
+
+Gets the content hash record for a specified name.
+
+Input:
+
+- `name`: string
+  - Target name
+
+Output:
+
+- object | null
+  - Decoded content hash
+
+### getText
+
+Gets a text record for a specified name.
+
+Input:
+
+- `name`: string
+  - Target name
+- `key`: string
+  - Target key
+
+Output:
+
+- string | null
+  - Text record value
+
+### getAddr
+
+Gets an address record for a specified name.
+
+Input:
+
+- `name`: string
+  - Target name
+- `coinType`: string? | number?
+  - Target coin
+  - Defaults to 60 (ETH) if undefined
+
+Output:
+
+- string | null
+  - Address record value
+
+### burnFuses
+
+Creates a transaction to burn fuses on a specified wrapped name.
+
+Input:
+
+- `name`: string
+  - Target name
+- `fusesToBurn`: object
+  - Object of fuses intended to be burned.
+
+Output:
+
+- transaction
+
+### createSubname
+
+Creates a subname using the specified contract.
+
+Input:
+
+- object
+  - `name`: string
+    - Target name
+  - `owner`: string
+    - New owner of subname
+  - `contract`: `registry` | `nameWrapper`
+    - Target contract
+  - `resolverAddress`: string?
+    - Resolver address for name
+  - `shouldWrap`: boolean?
+    - _Only valid with NameWrapper contract_
+    - Initial name wrapped state
+  - `fuses`: object?
+    - _Only valid with NameWrapper contract_
+    - Initial fuses to be burned
+
+Output:
+
+- transaction
+
+### deleteSubname
+
+Deletes a subname using the specified contract.
+
+Input:
+
+- `name`: string
+  - Target name
+- `contract`: `registry` | `nameWrapper`
+  - Target contract
+
+Output:
+
+- transaction
+
+### transferSubname
+
+Transfers a subname using the specified contract.
+**Please note that transferring a wrapped name using this method will unwrap the name.**
+
+Input:
+
+- `name`: string
+  - Target name
+- `contract`: `registry` | `nameWrapper`
+  - Target contract
+- `address`: string
+  - Address to transfer name to
+
+Output:
+
+- transaction
+
+### setName
+
+Sets the primary name for a specified address.
+
+Input:
+
+- `name`: string
+  - Name to set
+- `address`: string?
+  - _Setting other primary names requires authorisation_
+  - Address to set name for
+- `resolver`: string?
+  - _Setting other primary names requires authorisation_
+  - Target resolver
+
+Output:
+
+- transaction
+
+### setRecords
+
+Sets multiple records at once for the specified name.
+
+Input:
+
+- `name`: string
+  - Target name
+- `records`: object
+  - `contentHash`: string?
+    - Formatted and encoded content hash
+  - `texts`: array?
+    - object
+      - `key`: string
+        - Text key
+      - `value`: string
+        - Text value
+  - `coinTypes`: array?
+    - object
+      - `key`: string
+        - Coin name or ID
+      - `value`: string
+        - Coin address
+
+Output:
+
+- transaction
+
+### setResolver
+
+Sets the resolver for the specified name, using the specified contract.
+
+Input:
+
+- `name`: string
+  - Target Name
+- `contract`: `registry` | `nameWrapper`
+  - Target contract
+- `resolver`: string?
+  - _Leaving this undefined will use the default public resolver_
+
+Output:
+
+- transaction
+
+### transferName
+
+Transfers a name, using the specified contract.
+
+Input:
+
+- `name`: string
+  - Target name
+- `newOwner`: string
+  - Address to transfer name to
+- `contract`: `registry` | `nameWrapper` | `baseRegistrar`
+  - Target contract
+
+Output:
+
+- transaction
+
+### wrapName
+
+Wraps a name.
+
+Input:
+
+- `name`: string
+  - Target name
+- `wrappedOwner`: string
+  - New owner of wrapped name
+- `fuseOptions`: object?
+  - Initial fuses to burn
+- `resolverAddress`: string?
+  - Initial resolver address
+
+Output:
+
+- transaction
+
+### unwrapName
+
+Unwraps a name.
+
+Input:
+
+- `name`: string
+  - Target name
+- `newController`: string
+  - New controller for name
+- `newRegistrant`: string?
+  - New registrant for name
+
+Output:
+
+- transaction
+
+### universalWrapper
+
+Wraps a function so it is directed to the universal resolver instead of the default public resolver.
+
+Input:
+
+- `name`: string
+  - Name to resolve
+- `data`: string
+  - Hex encoded function data
+
+Output:
+
+- object
+  - `data`: string
+    - Hex encoded function result
+  - `resolver`: string
+    - Used resolver address
+
+Examples for universalWrapper can be found in `getSpecificRecord`.
+
+### resolverMulticallWrapper
+
+Wraps multiple resolver calls so they are made into a single resolver multicall.
+
+Input:
+
+- array
+  - object
+    - `to`: string
+      - Placeholder for standard function calls, ignore this.
+    - `data`: string
+      - Hex encoded function data
+
+Output:
+
+- array
+  - string
+    - Hex encoded function result
 
-Returns a Name Object that hardcodes the resolver
+Examples for resolverMulticallWrapper can be found in `getProfile`.