@ensnode/ensnode-sdk 0.31.0 → 0.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +150 -3
  2. package/dist/index.d.ts +1257 -46
  3. package/dist/index.js +1063 -48
  4. package/dist/index.js.map +1 -1
  5. package/package.json +7 -2
package/README.md CHANGED
@@ -1,9 +1,156 @@
1
1
  # ENSNode SDK
2
2
 
3
- This package is a set of libraries enabling smooth interaction with ENSNode services and data, including data processing (such as validating data and enforcing invariants), and ENS-oriented helper functions.
3
+ This package is a set of libraries enabling smooth interaction with ENSNode services and data, including shared types, data processing (such as validating data and enforcing invariants), and ENS-oriented helper functions.
4
4
 
5
5
  Learn more about [ENSNode](https://ensnode.io/) from [the ENSNode docs](https://ensnode.io/docs/).
6
6
 
7
- ## Package overview
7
+ ## Installation
8
8
 
9
- - [`utils`](utils) A utility library for interacting with ENS (Ethereum Name Service) data. It contains various helper functions and tools to facilitate interactions with ENS and ENSNode instances.
9
+ ```bash
10
+ npm install @ensnode/ensnode-sdk
11
+ ```
12
+
13
+ ## ENSNode Client
14
+
15
+ The `ENSNodeClient` provides a unified interface for the supported ENSNode APIs:
16
+ - Resolution API (Protocol Accelerated Forward/Reverse Resolution)
17
+ - 🚧 Configuration API
18
+ - 🚧 Indexing Status API
19
+
20
+ ### Basic Usage
21
+
22
+ ```typescript
23
+ import { ENSNodeClient, evmChainIdToCoinType } from "@ensnode/ensnode-sdk";
24
+ import { mainnet } from 'viem/chains';
25
+
26
+ const client = new ENSNodeClient();
27
+
28
+ // Resolution API: Records Resolution
29
+ const { records } = await client.resolveRecords("jesse.base.eth", {
30
+ addresses: [evmChainIdToCoinType(mainnet.id)],
31
+ texts: ["avatar", "com.twitter"],
32
+ });
33
+
34
+ // Resolution API: Primary Name Resolution
35
+ const { name } = await client.resolvePrimaryName("0x179A862703a4adfb29896552DF9e307980D19285", mainnet.id);
36
+ // name === 'gregskril.eth'
37
+
38
+ // Resolution API: Primary Names Resolution
39
+ const { names } = await client.resolvePrimaryNames("0x179A862703a4adfb29896552DF9e307980D19285");
40
+ // names === { '1': 'gregskril.eth', "8453": "greg.base.eth", ... }
41
+ ```
42
+
43
+ ### API Methods
44
+
45
+ #### Resolution API
46
+
47
+ ##### `resolveRecords(name, selection, options)`
48
+
49
+ Resolves records for an ENS name (Forward Resolution), via ENSNode, which implements Protocol Acceleration for indexed names.
50
+
51
+ - `name`: The ENS Name whose records to resolve
52
+ - `selection`: Optional selection of Resolver records:
53
+ - `addresses`: Array of coin types to resolve addresses for
54
+ - `texts`: Array of text record keys to resolve
55
+ - `options`: (optional) additional options
56
+ - `trace`: (optional) Whether to include a trace in the response (default: false)
57
+ - `accelerate`: (optional) Whether to attempt Protocol Acceleration (default: false)
58
+
59
+
60
+ ```ts
61
+ import { mainnet, base } from 'viem/chains';
62
+
63
+ const { records } = await client.resolveRecords("greg.base.eth", {
64
+ // Resolve ETH Mainnet Address (if set) and Base Address (if set)
65
+ addresses: [evmChainIdToCoinType(mainnet.id), evmChainIdToCoinType(base.id)],
66
+ // or pass the CoinTypes directly if you know them
67
+ // addresses: [60, 2147492101],
68
+ texts: ["avatar", "com.twitter"],
69
+ });
70
+
71
+ console.log(records);
72
+ // {
73
+ // "addresses": {
74
+ // "60": "0x179A862703a4adfb29896552DF9e307980D19285",
75
+ // "2147492101": "0x179A862703a4adfb29896552DF9e307980D19285"
76
+ // },
77
+ // "texts": {
78
+ // "avatar": "https://...",
79
+ // "com.twitter": "gregskril"
80
+ // }
81
+ // }
82
+ ```
83
+
84
+ ##### `resolvePrimaryName(address, chainId, options)`
85
+
86
+ Resolves the primary name of the provided `address` on the specified `chainId`, via ENSNode, which implements Protocol Acceleration for indexed names. If the `address` specifies a valid [ENSIP-19 Default Name](https://docs.ens.domains/ensip/19/#default-primary-name), the Default Name will be returned. You _may_ query the Default EVM Chain Id (`0`) in order to determine the `address`'s Default Name directly.
87
+
88
+ - `address`: The Address whose Primary Name to resolve
89
+ - `chainId`: The chain id within which to query the address' ENSIP-19 Multichain Primary Name
90
+ - `options`: (optional) additional options
91
+ - `trace`: (optional) Whether to include a trace in the response (default: false)
92
+ - `accelerate`: (optional) Whether to attempt Protocol Acceleration (default: false)
93
+
94
+ ```ts
95
+ import { mainnet, base } from 'viem/chains';
96
+ import { DEFAULT_EVM_CHAIN_ID } from '@ensnode/ensnode-sdk';
97
+
98
+ // Resolve the address' Primary Name on Ethereum Mainnet
99
+ const { name } = await client.resolvePrimaryName("0x179A862703a4adfb29896552DF9e307980D19285", mainnet.id);
100
+ // name === 'gregskril.eth'
101
+
102
+ // Resolve the address' Primary Name on Base
103
+ const { name } = await client.resolvePrimaryName("0x179A862703a4adfb29896552DF9e307980D19285", base.id);
104
+ // name === 'greg.base.eth'
105
+
106
+ // Resolve the address' Default Primary Name
107
+ const { name } = await client.resolvePrimaryName("0x179A862703a4adfb29896552DF9e307980D19285", DEFAULT_EVM_CHAIN_ID);
108
+ // name === 'gregskril.eth'
109
+ ```
110
+
111
+ ##### `resolvePrimaryNames(address, options)`
112
+
113
+ Resolves the primary names of the provided `address` on the specified chainIds, via ENSNode, which implements Protocol Acceleration for indexed names. If the `address` specifies a valid [ENSIP-19 Default Name](https://docs.ens.domains/ensip/19/#default-primary-name), the Default Name will be returned for all chainIds for which there is not a chain-specific Primary Name. To avoid misuse, you _may not_ query the Default EVM Chain Id (`0`) directly, and should rely on the aforementioned per-chain defaulting behavior.
114
+
115
+ - `address`: The Address whose Primary Names to resolve
116
+ - `options`: (optional) additional options
117
+ - `chainIds`: The chain ids within which to query the address' ENSIP-19 Multichain Primary Name (default: all ENSIP-19 supported chains)
118
+ - `trace`: (optional) Whether to include a trace in the response (default: false)
119
+ - `accelerate`: (optional) Whether to attempt Protocol Acceleration (default: false)
120
+
121
+ ```ts
122
+ import { mainnet, base } from 'viem/chains';
123
+
124
+ // Resolve an address' Primary Names on all ENSIP-19 supported chain ids
125
+ const { names } = await client.resolvePrimaryNames("0x179A862703a4adfb29896552DF9e307980D19285");
126
+
127
+ console.log(names);
128
+ // {
129
+ // "1": "gregskril.eth",
130
+ // "10": "gregskril.eth",
131
+ // "8453": "greg.base.eth", // base-specific Primary Name!
132
+ // "42161": "gregskril.eth",
133
+ // "59144": "gregskril.eth",
134
+ // "534352": "gregskril.eth"
135
+ // }
136
+
137
+ // Resolve an address' Primary Names on specific chain Ids
138
+ const { names } = await client.resolvePrimaryNames("0x179A862703a4adfb29896552DF9e307980D19285", {
139
+ chainIds: [mainnet.id, base.id],
140
+ });
141
+
142
+ console.log(names);
143
+ // {
144
+ // "1": "gregskril.eth",
145
+ // "8453": "greg.base.eth", // base-specific Primary Name!
146
+ // }
147
+ ```
148
+
149
+
150
+ ### Configuration
151
+
152
+ ```typescript
153
+ const client = new ENSNodeClient({
154
+ url: new URL("https://my-ensnode-instance.com"),
155
+ });
156
+ ```