BNS library feature scope

[agraebe]

Right now, the BNS library includes methods to interact with the BNS contract. With the recent addition of BNS API endpoints, there are several new fetching capabilities that are not directly implemented in the BNS contract (and not in the BNS library).

The question is: Should we extend the scope of the BNS library and include new capabilities provided by the API?

I would argue that developers using BNS shouldn't need to worry about the difference between the contract, API, or library. This is an additional burden to the onboarding flow that we can avoid to improve the developer experience. It would be great if the BNS library could be the go-to for all BNS features developers would care about.

In terms of BNS features that developers care about today, there's some signal from current research:

• Better UX: would like to display a human-readable username instead of the stacks address
• Simplified interactions: would like to send tokens to/from usernames instead of the stacks address

Another thing to note is that Hiro wallets are also not allowing users to register a username during the account creation process. The only registrar currently available is btc.us.

All things considered, I would assume that developers would mainly care about fetching capabilities (eg get username for an account). This would reason them not to use the BNS library and integrate the BNS API endpoints instead. Thus, limiting the impact of the BNS library. If we believe this is OK, and the scope should stay as is, we should explicitly communicate the scope of the library. For instance, BNS JS library for ...

• contract interaction
• writing operations
• registrar features

[kyranjamie]

Related #994

tl;dr: no

I opened this a while back as, at least in the use case described in this issue, we came across some difficulties owing to API requests being handled through stacks.js libs. We may well come across similar issues in future.

If we do allow users to invoke API requests through stacks.js libs, we must let the consumer configure all properties of the request. So this configuration-passing functionality also needs to be built into the BNS library.

Further, it also means that the library determines what http client lib the consumer uses. What if the package consumer want to use a different one? Do they have to bundle the one chosen here anyway? We don't know the environment this is being used, so you're forced to use cross-fetch and libraries like this. Consumer, can change the lib if it conforms to fetchs API, but they must to do so with their package-bundling tooling. A PITA.

My suggestion would be to prohibit all transport layer interaction in the BNS library (and most other packages), no http requests or side-effecty behaviour. Instead we could expose methods to help prepare these API requests, but not actually call them within. Can @stacks/bns play nice with our generated API client?

[kyranjamie]

To answer your questions:

1. Yes. Though encapsulating all functionality in a single package isn't the only way to do this.
2. If making network requests, then yes, its necessary to allow consumers to configure request. That's possible, but also quite some work to implement this in all packages that handle requests, I wouldn't recommend that path.
3. No. I don't think they should.

I didn't explain very clearly, my suggestion is not to put API requests in core packages at all.
#994 highlights issues caused by coupling API request logic in our core package utilities. Adding in HTTP request/client configuration functionality is more of a workaround than a solution.

Here's a fun ASCII diagram that illustrates the package dependency set up I'd advocate:

   +--------------------------+                                                
   |                          |                                                
   |                          |-\                                              
   |       @stacks/bns        |  ---\                                          
   |                          |      --\                                       
   |                          |         ---\          +-----------------------+
   +--------------------------+             --\       |                       |
                                               ---\   |   @stacks/bns-sdk     |
   +--------------------------+                   ----|                       |
   |                          |            ------/    |  developer-script.js  |
   |                          |    -------/           |                       |
   |  @stacks/{api/network}   |---/                   +-----------------------+
   |                          |                                                
   |                          |                                                
   +--------------------------+                                                

We should compose the packages in a way where core packages, like bns or transaction are concerned with preparing transactions, but not cause side-effects, like broadcasting them

Option 1 — A "smarter" SDK package

import { BnsClient } from '@stacks/bns-sdk';
const bns = new BnsClient().allTheMethodsYouNeedForBnsIncludingApiRequests();

Easy to use, but not necessary imo.

Option 2 — Developers compose packages themselves

import { buildPreorderNameTx } from '@stacks/bns';
import { broadcastTransaction } from '@stacks/api'; // or generated client lib

const preorderNameTx = await buildPreorderNameTx({ ...args });
const resp = await broadcastTransaction(preorderNameTx);

I prefer this option:

• Dev can compose what they need. We don't make assumptions on what HTTP client they use, how they configure their reqs etc
• @stacks/bns is a library concerned only with contract interaction fns with no side-effects

Hope I don't get accused of bike-shedding here lol, I just think we'd benefit from each package having slightly more scoped responsibilities.

[aulneau]

Hope I don't get accused of bike-shedding here lol, I just think we'd benefit from each package having slightly more scoped responsibilities.

This is a fantastic write up and in no way is it bikeshedding. These are all important things to consider and a direction I think we should go in.

[agraebe]

Agree with @aulneau! Not bikeshedding at all. It's a fantastic suggestion and I personally would also prefer option 2 after giving it more thought. @reedrosenbluth - any thoughts from your end?

[reedrosenbluth]

Awesome writeup @kyranjamie! I'm definitely in favor of this.

[zone117x]

My suggestion would be to prohibit all transport layer interaction in the BNS library (and most other packages), no http requests or side-effecty behaviour. Instead we could expose methods to help prepare these API requests, but not actually call them within

I agree, more explicit and less side effects sounds better. I think something like option 2 makes sense, but would be useful to have a more full example, because it might look like a lot more steps. For example, a network request needs to be made to get the fee, then to get the nonce, then build a final transaction, then a network request to broadcast the tx.

I'd predict complaints from devs if the "all-in-one" functions were removed, and a single function call had to be replaced by like 5 lines of code.

[friedger]

Using the node api client library inside stacks.js means that developers can only switch to a different node url if that node runs the stacks api server. This might not be the case. Therefore, I would try to create client libraries with clear requirements on the server. Probably developers run a custom stacks api server specific to their contracts.

[aulneau]

I would agree with @kyranjamie and try to have very clear definitions of what each package does. I think we should generally move away of having "one package to rule them all" for a given category of functionality. The most complex and confusing things about BNS are how to construct the arguments needed for the various contract functions.

Better UX: would like to display a human-readable username instead of the stacks address
Simplified interactions: would like to send tokens to/from usernames instead of the stacks address

To me, these don't seem related to the BNS library at all, but instead these should be exposed via connect and the transactions lib. Perhaps these libraries would implement some BNS-sdk package.