Let Address.fromString resolve human-readable names through a registered resolver

[LusoCryptoLabs]

Address.fromString only understands addresses. A wallet or dapp that wants to accept a name where an address goes (alice.example instead of ckt1q...) has to special-case it before calling CCC, and every one of them does that again.

Proposal: one small hook, off by default.

Address.registerNameResolver({
  suffixes: [".example"],
  resolve: async (name, client) => lookup(name), // a CKB address string, or null
});
await Address.fromString("alice.example", client);

fromString would behave exactly as today for every input it accepts today. Only when parsing fails, a resolver is registered, and the string ends with one of its suffixes, is the resolver asked for an address, which is then parsed the ordinary way, so nothing a resolver returns can skip the usual checks. A record of clients keyed by prefix cannot be matched to a name, so a name would resolve only against a single client; anything else stays unresolved rather than guessed.

Two shapes are possible and I would rather ask than pick:

1. A static registry on Address, as above: one call at startup, works
   everywhere an address is parsed. Simplest for wallets; it is global state.
2. A resolver carried by the Client (an option, or a method), so it scopes
   with the client and nothing is global. One more thing to pass around.

Motivation: names on CKB exist already (.bit) and CCC has nowhere to plug them
in; I am building another registry with an HTTP resolver, and its client would
register itself here with one call. The hook itself is not specific to any of
them.

I have a small patch with tests for shape 1 (about 100 lines plus tests, no new
dependencies) and can open it as a PR if either shape is welcome.

[Hanssen0]

Hi @LusoCryptoLabs! Thank you for the proposal.

Indeed, this could be a highly promising change. The way this feature is implemented could have a significant impact on the diverse address display formats of the future. I was going to suggest: could we consider adding an extra address resolver class to handle this? Is it really necessary to place this level of abstraction on the Address itself? However, considering usability, placing it on Address might actually be the best option.

I wouldn't consider Address.registerNameResolver a particularly good idea, especially when you take into account the unpredictability of global objects regarding cross-version dependencies. Adding a new method to the client might be a good approach, especially considering that we are already passing the client object to fromString.

[LusoCryptoLabs]

Agreed, and the objection is the right one. Shape 2 it is.

I can put numbers on it from this side rather than argue it in principle. This repository
has seven copies of @ckb-ccc/core in one working tree: six because six packages here
each declare it, and a seventh at 0.1.2 that arrives nested under a transitive dependency
and that nobody here asked for. Separately, when I tried 1.22.0 at the root, npm nested
1.19.1 under each of the fourteen packages in the connector's own tree that pin it
exactly, leaving fifteen copies in one node_modules. In any of those trees a resolver
registered on one copy's Address is invisible to the other, and the failure is the quiet
one: a name that does not resolve, with nothing on screen to say why.

The smallest shape I can see is on the config that already exists:

// packages/core/src/client/client.ts
export type NameResolver = {
  /** The suffixes this resolver claims, for example [".bit"]. */
  suffixes: string[];
  /** A CKB address string, or null when the name is unknown. */
  resolve(name: string, client: Client): Promise<string | null>;
};

export type ClientConfig = {
  cache?: ClientCache;
  scripts?: Partial<Record<KnownScript, ScriptInfoLike>>;
  nameResolver?: NameResolver;
};

Address.fromString would ask only when addressPayloadFromString throws, a resolver is
configured, and the string ends in one of its suffixes. The suffix list is there so a
mistyped address does not become a network request. Whatever the resolver returns is
parsed the ordinary way, so nothing it returns can skip a check that exists today, and
every input that parses now keeps parsing identically.

Two things I would rather ask than decide.

A new field on ClientConfig is carried by the constructor and dropped by the
factories. new ClientPublicTestnet({ nameResolver }) works: resolveConfig spreads
...config and ClientJsonRpc passes the whole object to super(config). But
ClientPublicTestnet.new and .open, and the same two on ClientPublicMainnet, do
const { cache, scripts, ...requestorConfig } = config and then rebuild the client from
the named fields, so anything added to ClientConfig is silently discarded on those four
paths. That is the same shape of problem you raised about the global, only smaller and
closer to home: a value that is lost because somewhere was not updated. So either those
four learn the field, or the resolver lives on the instance instead and cannot be lost by
a factory. By "Design for the Majority" I would guess the config field, since that is
where a reader looks first; by "Good Developer Experience" I would guess the instance,
since nothing can quietly drop it. I do not have a view strong enough to override yours.

The Record<string, Client> overload. A name has no prefix to key on, so I would
resolve against a single Client only and leave the record case unresolved rather than
guess which client was meant. Say if you would rather it threw something specific there.

Happy to open the PR once you have picked, with tests and a changeset.