🚧 WIP [next] feat!: refactor stacks.js

[janniks]

💡 To reduce reviewing difficulty some PRs will merge into this branch. Also no real "logic" is changed here, to keep it simple.

High-level changes:

• Move to new @stacks/api package (main way to do networking for users)
• Move to static "network" objects (simpler way to specify opts for methods)

---

Refactor 🚂

• Removes @stacks/network package
  • Moves most functionality to transactions package (this will become the main package allowing most folks to use it and not need to worry about other imports)
  • Move to a network OBJECT approach (similar to bitcoin-js, micro-btc-signer, and others). The network will not be an instantiated class, but a static exported object with all information that might be relevant (txVersion, magicBytes, etc.)
  • Remove fetch functions from network and introduce StacksNodeApi, which can derive it's URL from a network, but should be treated separately -- more closely mirroring to what's actually happening in the background.
  • The majority of users doesn't realize network is also setting changes for "networking"
    • Most users don't customize fetchFn or URL. For users hosting their own node the only change becomes { api: { url: "my-node.com" }, ...} in the params of most relevant tx functions.
• Removes duplicate/unnecessary definitions from @stacks/common

Some changes might irritate users at first, but I think it's an approach that follows the structure of the blockchain and in a way educated while using the library. More to follow

Curious to get feedback 🙏 @hugocaillard @zone117x @rafaelcr

Open Questions:

• Thoughts on param naming?
  • Should url be baseUrl, or nodeUrl?
  • Should StacksApi be StacksNode or StacksNodeApi ✅
    • I like it short, but "node" could be helpful (even though most users wrap their node with the API). We could also add a "node-only mode" which ensures the requests it's trying to make exist on the v2 rather than extended.
• What should live where?
  • Should we move most things into @stacks/transactions (is there a case for having users import from @stacks/common for basic interactions or should it stay for helpers used by all @stacks/ packages?) common will be non-Stacks things, transactions will be the main package ✅

Examples

Diff for most methods

const transaction = await makeSTXTokenTransfer({
  recipient,
  amount,
  senderKey,
  memo,
- network: new StacksTestnet({ url: "mynode-optional.com" }), // optional options
+ network: STACKS_TESTNET,
+ api: { url: "mynode-optional.com" } // optional param
});

String enum params still work (e.g. 'testnet') ☝️

New API class

const api = new StacksNodeApi({ network: STACKS_TESTNET });
await api.broadcastTransaction(tx); // bundled client, discoverable API maintained endpoints/methods (with helper processing/decoding)

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
stacksjs-docs	❌ Failed (Inspect)			Dec 18, 2023 3:42pm

[janniks]

Any other thoughts on this change? @zone117x
I still don't like the separation of common+transactions. It's super unclear when something should be in which.
Currently common houses things like TransactionVersion/ChainID which is very transactiony. 😅

For dependents it doesn't really matter, since pretty much everything already imports from transaction

A) Do you think we could remove the package and move its contents to transactions?
B) Or maybe move most things to transactions, and leave common for very pure "helpers" (e.g. buffer, bytes, hex).

I'm thinking if most people also need to do text<>hex conversion or similar, we might as well do everything in transactions, so folks only need one dependency for 95% of use-cases.

[zone117x]

Hmm good arguments for both options. I don't really have a strong opinion. Kinda lean towards keeping the common package so that other packages aren't transitively dependent on the transaction package for helpers that are unrelated to transactions

[janniks]

Splitting this out into separate PRs

[janniks]

closed in favor of #1622