ethers.js/src.ts/providers/ens-resolver.ts

560 lines
20 KiB
TypeScript
Raw Normal View History

2022-12-06 07:45:08 +03:00
/**
* About ENS Resolver
*
* @_section: api/providers/ens-resolver:ENS Resolver [about-ens-rsolver]
*/
import { ZeroAddress } from "../constants/index.js";
import { Contract } from "../contract/index.js";
2022-09-05 23:14:43 +03:00
import { dnsEncode, namehash } from "../hash/index.js";
import {
hexlify, toBeHex,
defineProperties, encodeBase58,
assert, assertArgument, isError,
FetchRequest
2022-09-05 23:14:43 +03:00
} from "../utils/index.js";
import type { FunctionFragment } from "../abi/index.js";
import type { BytesLike } from "../utils/index.js";
2022-09-05 23:14:43 +03:00
2022-11-09 10:51:07 +03:00
import type { AbstractProvider, AbstractProviderPlugin } from "./abstract-provider.js";
2022-09-05 23:14:43 +03:00
import type { EnsPlugin } from "./plugins-network.js";
import type { Provider } from "./provider.js";
2022-09-05 23:14:43 +03:00
// @TODO: This should use the fetch-data:ipfs gateway
// Trim off the ipfs:// prefix and return the default gateway URL
function getIpfsLink(link: string): string {
if (link.match(/^ipfs:\/\/ipfs\//i)) {
link = link.substring(12);
} else if (link.match(/^ipfs:\/\//i)) {
link = link.substring(7);
} else {
assertArgument(false, "unsupported IPFS format", "link", link);
2022-09-05 23:14:43 +03:00
}
return `https:/\/gateway.ipfs.io/ipfs/${ link }`;
}
2022-12-06 07:45:08 +03:00
/**
* The type of data found during a steip during avatar resolution.
*/
2022-09-05 23:14:43 +03:00
export type AvatarLinkageType = "name" | "avatar" | "!avatar" | "url" | "data" | "ipfs" |
"erc721" | "erc1155" | "!erc721-caip" | "!erc1155-caip" |
"!owner" | "owner" | "!balance" | "balance" |
"metadata-url-base" | "metadata-url-expanded" | "metadata-url" | "!metadata-url" |
"!metadata" | "metadata" |
"!imageUrl" | "imageUrl-ipfs" | "imageUrl" | "!imageUrl-ipfs";
2022-12-06 07:45:08 +03:00
/**
* An individual record for each step during avatar resolution.
*/
2022-09-05 23:14:43 +03:00
export interface AvatarLinkage {
type: AvatarLinkageType;
value: string;
};
2022-12-06 07:45:08 +03:00
/**
* When resolving an avatar for an ENS name, there are many
* steps involved, fetching metadata, validating results, et cetera.
*
* Some applications may wish to analyse this data, or use this data
* to diagnose promblems, so an **AvatarResult** provides details of
* each completed step during avatar resolution.
*/
2022-09-05 23:14:43 +03:00
export interface AvatarResult {
linkage: Array<AvatarLinkage>;
url: null | string;
};
2022-12-06 07:45:08 +03:00
/**
* A provider plugin super-class for processing multicoin address types.
*/
2022-11-09 10:51:07 +03:00
export abstract class MulticoinProviderPlugin implements AbstractProviderPlugin {
2022-09-05 23:14:43 +03:00
readonly name!: string;
constructor(name: string) {
defineProperties<MulticoinProviderPlugin>(this, { name });
}
2022-11-09 10:51:07 +03:00
connect(proivder: Provider): MulticoinProviderPlugin {
2022-09-05 23:14:43 +03:00
return this;
}
supportsCoinType(coinType: number): boolean {
return false;
}
async encodeAddress(coinType: number, address: string): Promise<string> {
throw new Error("unsupported coin");
}
async decodeAddress(coinType: number, data: BytesLike): Promise<string> {
throw new Error("unsupported coin");
}
}
const BasicMulticoinPluginId = "org.ethers.plugins.provider.BasicMulticoin";
2022-09-05 23:14:43 +03:00
2022-12-06 07:45:08 +03:00
/**
* A basic multicoin provider plugin.
*/
2022-09-05 23:14:43 +03:00
export class BasicMulticoinProviderPlugin extends MulticoinProviderPlugin {
constructor() {
super(BasicMulticoinPluginId);
}
}
const matcherIpfs = new RegExp("^(ipfs):/\/(.*)$", "i");
const matchers = [
new RegExp("^(https):/\/(.*)$", "i"),
new RegExp("^(data):(.*)$", "i"),
matcherIpfs,
new RegExp("^eip155:[0-9]+/(erc[0-9]+):(.*)$", "i"),
];
2022-12-06 07:45:08 +03:00
/**
* A connected object to a resolved ENS name resolver, which can be
* used to query additional details.
*/
2022-09-05 23:14:43 +03:00
export class EnsResolver {
2022-12-06 07:45:08 +03:00
/**
* The connected provider.
*/
2022-09-05 23:14:43 +03:00
provider!: AbstractProvider;
2022-12-06 07:45:08 +03:00
/**
* The address of the resolver.
*/
2022-09-05 23:14:43 +03:00
address!: string;
2022-12-06 07:45:08 +03:00
/**
* The name this resovler was resolved against.
*/
2022-09-05 23:14:43 +03:00
name!: string;
// For EIP-2544 names, the ancestor that provided the resolver
#supports2544: null | Promise<boolean>;
#resolver: Contract;
2022-09-05 23:14:43 +03:00
constructor(provider: AbstractProvider, address: string, name: string) {
defineProperties<EnsResolver>(this, { provider, address, name });
this.#supports2544 = null;
this.#resolver = new Contract(address, [
"function supportsInterface(bytes4) view returns (bool)",
"function resolve(bytes, bytes) view returns (bytes)",
"function addr(bytes32) view returns (address)",
"function addr(bytes32, uint) view returns (address)",
"function text(bytes32, string) view returns (string)",
"function contenthash() view returns (bytes)",
], provider);
2022-09-05 23:14:43 +03:00
}
2022-12-06 07:45:08 +03:00
/**
* Resolves to true if the resolver supports wildcard resolution.
*/
2022-09-05 23:14:43 +03:00
async supportsWildcard(): Promise<boolean> {
if (this.#supports2544 == null) {
this.#supports2544 = (async () => {
try {
return await this.#resolver.supportsInterface("0x9061b923");
} catch (error) {
// Wildcard resolvers must understand supportsInterface
// and return true.
if (isError(error, "CALL_EXCEPTION")) { return false; }
// Let future attempts try again...
this.#supports2544 = null;
throw error;
}
})();
2022-09-05 23:14:43 +03:00
}
return await this.#supports2544;
}
async #fetch(funcName: string, params?: Array<any>): Promise<null | any> {
params = (params || []).slice();
const iface = this.#resolver.interface;
// The first parameters is always the nodehash
params.unshift(namehash(this.name))
let fragment: null | FunctionFragment = null;
2022-09-05 23:14:43 +03:00
if (await this.supportsWildcard()) {
fragment = iface.getFunction(funcName);
assert(fragment, "missing fragment", "UNKNOWN_ERROR", {
info: { funcName }
});
2022-09-05 23:14:43 +03:00
params = [
dnsEncode(this.name),
iface.encodeFunctionData(fragment, params)
];
funcName = "resolve(bytes,bytes)";
2022-09-05 23:14:43 +03:00
}
params.push({
ccipReadEnable: true
});
2022-09-05 23:14:43 +03:00
try {
const result = await this.#resolver[funcName](...params);
if (fragment) {
return iface.decodeFunctionResult(fragment, result)[0];
}
return result;
2022-09-05 23:14:43 +03:00
} catch (error: any) {
if (!isError(error, "CALL_EXCEPTION")) { throw error; }
2022-09-05 23:14:43 +03:00
}
return null;
}
2022-12-06 07:45:08 +03:00
/**
* Resolves to the address for %%coinType%% or null if the
* provided %%coinType%% has not been configured.
*/
2022-11-28 05:58:07 +03:00
async getAddress(coinType?: number): Promise<null | string> {
if (coinType == null) { coinType = 60; }
2022-09-05 23:14:43 +03:00
if (coinType === 60) {
try {
const result = await this.#fetch("addr(bytes32)");
2022-09-05 23:14:43 +03:00
// No address
if (result == null || result === ZeroAddress) { return null; }
2022-09-05 23:14:43 +03:00
return result;
2022-09-05 23:14:43 +03:00
} catch (error: any) {
if (isError(error, "CALL_EXCEPTION")) { return null; }
2022-09-05 23:14:43 +03:00
throw error;
}
}
let coinPlugin: null | MulticoinProviderPlugin = null;
for (const plugin of this.provider.plugins) {
if (!(plugin instanceof MulticoinProviderPlugin)) { continue; }
if (plugin.supportsCoinType(coinType)) {
coinPlugin = plugin;
break;
}
}
if (coinPlugin == null) { return null; }
// keccak256("addr(bytes32,uint256")
const data = await this.#fetch("addr(bytes32,uint)", [ coinType ]);
2022-09-05 23:14:43 +03:00
// No address
if (data == null || data === "0x") { return null; }
// Compute the address
const address = await coinPlugin.encodeAddress(coinType, data);
if (address != null) { return address; }
assert(false, `invalid coin data`, "UNSUPPORTED_OPERATION", {
2022-09-05 23:14:43 +03:00
operation: `getAddress(${ coinType })`,
info: { coinType, data }
});
}
2022-12-06 07:45:08 +03:00
/**
* Resovles to the EIP-643 text record for %%key%%, or ``null``
* if unconfigured.
*/
2022-09-05 23:14:43 +03:00
async getText(key: string): Promise<null | string> {
const data = await this.#fetch("text(bytes32,string)", [ key ]);
if (data == null || data === "0x") { return null; }
return data;
2022-09-05 23:14:43 +03:00
}
2022-12-06 07:45:08 +03:00
/**
* Rsolves to the content-hash or ``null`` if unconfigured.
*/
2022-09-05 23:14:43 +03:00
async getContentHash(): Promise<null | string> {
// keccak256("contenthash()")
const data = await this.#fetch("contenthash()");
2022-09-05 23:14:43 +03:00
// No contenthash
if (data == null || data === "0x") { return null; }
2022-09-05 23:14:43 +03:00
// IPFS (CID: 1, Type: 70=DAG-PB, 72=libp2p-key)
const ipfs = data.match(/^0x(e3010170|e5010172)(([0-9a-f][0-9a-f])([0-9a-f][0-9a-f])([0-9a-f]*))$/);
2022-09-05 23:14:43 +03:00
if (ipfs) {
const scheme = (ipfs[1] === "e3010170") ? "ipfs": "ipns";
const length = parseInt(ipfs[4], 16);
if (ipfs[5].length === length * 2) {
return `${ scheme }:/\/${ encodeBase58("0x" + ipfs[2])}`;
}
}
// Swarm (CID: 1, Type: swarm-manifest; hash/length hard-coded to keccak256/32)
const swarm = data.match(/^0xe40101fa011b20([0-9a-f]*)$/)
2022-09-05 23:14:43 +03:00
if (swarm && swarm[1].length === 64) {
return `bzz:/\/${ swarm[1] }`;
}
assert(false, `invalid or unsupported content hash data`, "UNSUPPORTED_OPERATION", {
2022-09-05 23:14:43 +03:00
operation: "getContentHash()",
info: { data }
2022-09-05 23:14:43 +03:00
});
}
2022-12-06 07:45:08 +03:00
/**
* Resolves to the avatar url or ``null`` if the avatar is either
* unconfigured or incorrectly configured (e.g. references an NFT
* not owned by the address).
*
* If diagnosing issues with configurations, the [[_getAvatar]]
* method may be useful.
*/
2022-09-05 23:14:43 +03:00
async getAvatar(): Promise<null | string> {
const avatar = await this._getAvatar();
return avatar.url;
2022-09-05 23:14:43 +03:00
}
2022-12-06 07:45:08 +03:00
/**
* When resolving an avatar, there are many steps involved, such
* fetching metadata and possibly validating ownership of an
* NFT.
*
* This method can be used to examine each step and the value it
* was working from.
*/
2022-09-05 23:14:43 +03:00
async _getAvatar(): Promise<AvatarResult> {
const linkage: Array<AvatarLinkage> = [ { type: "name", value: this.name } ];
try {
// test data for ricmoo.eth
//const avatar = "eip155:1/erc721:0x265385c7f4132228A0d54EB1A9e7460b91c0cC68/29233";
const avatar = await this.getText("avatar");
if (avatar == null) {
linkage.push({ type: "!avatar", value: "" });
return { url: null, linkage };
2022-09-05 23:14:43 +03:00
}
linkage.push({ type: "avatar", value: avatar });
for (let i = 0; i < matchers.length; i++) {
const match = avatar.match(matchers[i]);
if (match == null) { continue; }
const scheme = match[1].toLowerCase();
switch (scheme) {
case "https":
case "data":
linkage.push({ type: "url", value: avatar });
return { linkage, url: avatar };
case "ipfs": {
const url = getIpfsLink(avatar);
linkage.push({ type: "ipfs", value: avatar });
linkage.push({ type: "url", value: url });
return { linkage, url };
}
case "erc721":
case "erc1155": {
// Depending on the ERC type, use tokenURI(uint256) or url(uint256)
const selector = (scheme === "erc721") ? "tokenURI(uint256)": "uri(uint256)";
2022-09-05 23:14:43 +03:00
linkage.push({ type: scheme, value: avatar });
// The owner of this name
const owner = await this.getAddress();
if (owner == null) {
linkage.push({ type: "!owner", value: "" });
return { url: null, linkage };
2022-09-05 23:14:43 +03:00
}
const comps = (match[2] || "").split("/");
if (comps.length !== 2) {
linkage.push({ type: <any>`!${ scheme }caip`, value: (match[2] || "") });
return { url: null, linkage };
2022-09-05 23:14:43 +03:00
}
const tokenId = comps[1];
const contract = new Contract(comps[0], [
// ERC-721
"function tokenURI(uint) view returns (string)",
"function ownerOf(uint) view returns (address)",
// ERC-1155
"function uri(uint) view returns (string)",
"function balanceOf(address, uint256) view returns (uint)"
], this.provider);
2022-09-05 23:14:43 +03:00
// Check that this account owns the token
if (scheme === "erc721") {
const tokenOwner = await contract.ownerOf(tokenId);
2022-09-05 23:14:43 +03:00
if (owner !== tokenOwner) {
linkage.push({ type: "!owner", value: tokenOwner });
return { url: null, linkage };
2022-09-05 23:14:43 +03:00
}
linkage.push({ type: "owner", value: tokenOwner });
} else if (scheme === "erc1155") {
const balance = await contract.balanceOf(owner, tokenId);
2022-09-05 23:14:43 +03:00
if (!balance) {
linkage.push({ type: "!balance", value: "0" });
return { url: null, linkage };
2022-09-05 23:14:43 +03:00
}
linkage.push({ type: "balance", value: balance.toString() });
}
// Call the token contract for the metadata URL
let metadataUrl = await contract[selector](tokenId);
if (metadataUrl == null || metadataUrl === "0x") {
2022-09-05 23:14:43 +03:00
linkage.push({ type: "!metadata-url", value: "" });
return { url: null, linkage };
2022-09-05 23:14:43 +03:00
}
linkage.push({ type: "metadata-url-base", value: metadataUrl });
// ERC-1155 allows a generic {id} in the URL
if (scheme === "erc1155") {
metadataUrl = metadataUrl.replace("{id}", toBeHex(tokenId, 32).substring(2));
2022-09-05 23:14:43 +03:00
linkage.push({ type: "metadata-url-expanded", value: metadataUrl });
}
// Transform IPFS metadata links
if (metadataUrl.match(/^ipfs:/i)) {
metadataUrl = getIpfsLink(metadataUrl);
}
linkage.push({ type: "metadata-url", value: metadataUrl });
// Get the token metadata
let metadata: any = { };
const response = await (new FetchRequest(metadataUrl)).send();
response.assertOk();
try {
metadata = response.bodyJson;
} catch (error) {
try {
linkage.push({ type: "!metadata", value: response.bodyText });
} catch (error) {
const bytes = response.body;
if (bytes) {
linkage.push({ type: "!metadata", value: hexlify(bytes) });
}
return { url: null, linkage };
2022-09-05 23:14:43 +03:00
}
return { url: null, linkage };
2022-09-05 23:14:43 +03:00
}
if (!metadata) {
linkage.push({ type: "!metadata", value: "" });
return { url: null, linkage };
2022-09-05 23:14:43 +03:00
}
linkage.push({ type: "metadata", value: JSON.stringify(metadata) });
// Pull the image URL out
let imageUrl = metadata.image;
if (typeof(imageUrl) !== "string") {
linkage.push({ type: "!imageUrl", value: "" });
return { url: null, linkage };
2022-09-05 23:14:43 +03:00
}
if (imageUrl.match(/^(https:\/\/|data:)/i)) {
// Allow
} else {
// Transform IPFS link to gateway
const ipfs = imageUrl.match(matcherIpfs);
if (ipfs == null) {
linkage.push({ type: "!imageUrl-ipfs", value: imageUrl });
return { url: null, linkage };
2022-09-05 23:14:43 +03:00
}
linkage.push({ type: "imageUrl-ipfs", value: imageUrl });
imageUrl = getIpfsLink(imageUrl);
}
linkage.push({ type: "url", value: imageUrl });
return { linkage, url: imageUrl };
}
}
}
} catch (error) { }
2022-09-05 23:14:43 +03:00
return { linkage, url: null };
}
static async getEnsAddress(provider: Provider): Promise<string> {
const network = await provider.getNetwork();
const ensPlugin = network.getPlugin<EnsPlugin>("org.ethers.plugins.network.Ens");
// No ENS...
assert(ensPlugin, "network does not support ENS", "UNSUPPORTED_OPERATION", {
operation: "getEnsAddress", info: { network } });
return ensPlugin.address;
}
2022-09-05 23:14:43 +03:00
static async #getResolver(provider: Provider, name: string): Promise<null | string> {
const ensAddr = await EnsResolver.getEnsAddress(provider);
2022-09-05 23:14:43 +03:00
try {
const contract = new Contract(ensAddr, [
"function resolver(bytes32) view returns (address)"
], provider);
const addr = await contract.resolver(namehash(name), {
2022-09-05 23:14:43 +03:00
enableCcipRead: true
});
if (addr === ZeroAddress) { return null; }
2022-09-05 23:14:43 +03:00
return addr;
} catch (error) {
// ENS registry cannot throw errors on resolver(bytes32),
// so probably a link error
throw error;
}
return null;
}
2022-12-06 07:45:08 +03:00
/**
* Resolve to the ENS resolver for %%name%% using %%provider%% or
* ``null`` if unconfigured.
2022-12-06 07:45:08 +03:00
*/
2022-09-05 23:14:43 +03:00
static async fromName(provider: AbstractProvider, name: string): Promise<null | EnsResolver> {
let currentName = name;
while (true) {
if (currentName === "" || currentName === ".") { return null; }
// Optimization since the eth node cannot change and does
// not have a wildcar resolver
if (name !== "eth" && currentName === "eth") { return null; }
// Check the current node for a resolver
const addr = await EnsResolver.#getResolver(provider, currentName);
// Found a resolver!
if (addr != null) {
const resolver = new EnsResolver(provider, addr, name);
// Legacy resolver found, using EIP-2544 so it isn't safe to use
if (currentName !== name && !(await resolver.supportsWildcard())) { return null; }
return resolver;
}
// Get the parent node
currentName = currentName.split(".").slice(1).join(".");
}
}
}