@ensdomains/ensjs 3.0.0-alpha.9 → 3.0.0-beta.1

package/README.md

@@ -1,716 +1,45 @@
 # ![ENSjs](https://user-images.githubusercontent.com/11844316/161689061-98ea01ee-b119-40ac-a512-5370eb8b4107.svg)
 
-The ultimate ENS javascript library, with [ethers.js](https://github.com/ethers-io/ethers.js) under the hood.
-
-## NOTE!!!
-
-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.
-
-Given the current development status, we're actively seeking feedback so feel free to create an issue or PR if you notice something!
-
-If you are looking for documentation for **version 2**, it an be found [here](https://github.com/ensdomains/ensjs#readme).
+The ultimate ENS javascript library, with [viem](https://github.com/wagmi-dev/viem) under the hood.
 
 ## Features
 
-- Dynamically load **everything**
-- Super fast response times (1 call for most RPC calls)
+- Super fast response times
 - Easy call batchability
 - Written in TypeScript
 - Supports the most cutting edge ENS features
-- - More
+- Full tree-shaking support
 
 ## Installation
 
-Install @ensdomains/ensjs, alongside [ethers](https://github.com/ethers-io/ethers.js).
+Install @ensdomains/ensjs, alongside [viem](https://github.com/wagmi-dev/viem).
 
 ```sh
-npm install @ensdomains/ensjs ethers
+npm install @ensdomains/ensjs viem
 ```
 
 ## Getting Started
 
-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'
-
-const provider = new ethers.providers.JsonRpcProvider(providerUrl)
-
-const ENSInstance = new ENS()
-await ENSInstance.setProvider(provider)
-```
-
-## 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,
-  ]
-*/
-```
-
-## Using Custom Graph Node URIs
-
-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`.
-
-```js
-import { ENS } from '@ensdomains/ensjs'
-
-/* 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 })
-```
-
-## Single-use Providers
-
-If you want to use a specific provider to make a single call occasionally, you can easily do so.
-
-```js
-import { ENS } from '@ensdomains/ensjs'
-
-const ENSInstance = new ENS()
-
-const callWithProvider = await ENSInstance.withProvider(otherProvider).getText(
-  'test.eth',
-  'foo',
-)
-```
-
-## 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')
+The most simple way to get started is to create a public ENS client, with a supported
+chain and transport imported from viem. The public client has all the read functions available on it,
+as well as all subgraph functions.
 
-/* Profile fetching from an address */
-const profile = await ENSInstance.getProfile(
-  '0xeefB13C7D42eFCc655E528dA6d6F7bBcf9A2251d',
-)
+```ts
+// Import viem transport, viem chain, and ENSjs
+import { http } from 'viem'
+import { mainnet } from 'viem/chains'
+import { createEnsPublicClient } from '@ensdomains/ensjs'
 
-/* Get all records of a specific type (or multiple) */
-const profile = await ENSInstance.getProfile('test.eth', {
-  texts: true,
-  coinTypes: true,
-  contentHash: true,
+// Create the client
+const client = createEnsPublicClient({
+  chain: mainnet,
+  transport: http(),
 })
 
-/* Get specific records */
-const profile = await ENSInstance.getProfile('test.eth', {
-  texts: ['foo'],
-  coinTypes: ['ETH'],
-})
-```
-
-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
-}
-```
-
-## Name History
-
-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.
-
-```js
-/* Normal Fetching, requires a second function for more details */
-const history = await ENSInstance.getHistory('test.eth')
-
-/* 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')
+// Use the client
+const ethAddress = client.getAddressRecord({ name: 'ens.eth' })
 ```
 
-## Ownership Levels
-
-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.
-
-## Wrapping Names
-
-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.
-
-```js
-/* wrap a .eth name */
-const tx = await ENSInstance.wrapName(
-  'test.eth', // Name to wrap
-  '0xeefB13C7D42eFCc655E528dA6d6F7bBcf9A2251d', // New owner of wrapped name
-)
-
-/* wrap any other name (e.g. a subname) */
-const tx = await ENSInstance.wrapName(
-  'sub.test.eth',
-  '0xeefB13C7D42eFCc655E528dA6d6F7bBcf9A2251d',
-)
-```
-
-## Write Transaction Options
-
-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.
-
-## Internal Structure
-
-### Raw Functions
-
-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.
-
-### importGenerator
-
-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:
-
-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
-
-### ContractManager
-
-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.
-
-### GqlManager
-
-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.
-
-### initialProvider
-
-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.
-
-## Individual Functions
-
-### getFuses
-
-Gets the fuses for a specified wrapped name.
-
-Input:
-
-- `name`: string
-  - Target name
-
-Output:
-
-- `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
+## Docs
 
-Examples for resolverMulticallWrapper can be found in `getProfile`.
+Docs can be found [here](https://github.com/ensdomains/ensjs-v3/tree/main/docs). Full docs site coming soon.