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

.github/MIGRATION.md

@@ -1,7 +1,11 @@
 # Migration Guides
 
-- [Stacks.js (\<=4.x.x) → (5.x.x)](#stacksjs-4xx--5xx)
+- [Stacks.js (\>=5.x.x) → (7.x.x)](#stacksjs-5xx--7xx)
   - [Breaking Changes](#breaking-changes)
+  - [StacksNodeApi](#stacksnodeapi)
+  - [StacksNetwork to StacksNodeApi](#stacksnetwork-to-stacksnodeapi)
+- [Stacks.js (\<=4.x.x) → (5.x.x)](#stacksjs-4xx--5xx)
+  - [Breaking Changes](#breaking-changes-1)
     - [Buffer to Uint8Array](#buffer-to-uint8array)
     - [Message Signing Prefix](#message-signing-prefix)
 - [blockstack.js → Stacks.js (1.x.x)](#blockstackjs--stacksjs-1xx)
@@ -14,6 +18,84 @@
     - [Using blockstack.js](#using-blockstackjs-2)
     - [Using @stacks/encryption or @stacks/auth](#using-stacksencryption-or-stacksauth)
 
+## Stacks.js (&gt;=5.x.x) → (7.x.x)
+
+### Breaking Changes
+
+- The `@stacks/network` package was removed. Similar functionality is now available in `@stacks/transactions`. [Read more...](#stacksnetwork-to-stacksnodeapi)
+
+### StacksNodeApi
+
+The new `StacksNodeApi` class lets you interact with a Stacks node or API.
+
+<!-- todo: move to separate package (which nothing depends on, now that there is an ApiParam, ie not circular deps) -->
+
+```ts
+import { StacksNodeApi } from '@stacks/transactions';
+
+const api = new StacksNodeApi();
+await api.broadcastTx(txHex);
+```
+
+### StacksNetwork to StacksNodeApi
+
+Stacks network objects are now exported by the `@stacks/common` package.
+They are used to specify network settings for other functions and don't require instantiation (like the `@stacks/network` approach did).
+
+```ts
+import { STACKS_MAINNET } from '@stacks/transactions';
+```
+
+After importing the network object (e.g. `STACKS_MAINNET` here), you can use it in other functions like so:
+
+```ts
+// todo: update more functions, show example
+```
+
+For easing the transition, the functions which depended on the networking aspect of `@stacks/network` now accept an `api` parameter.
+The `api` parameter can be an instance of `StacksNodeApi` or any object containing a `url` and `fetch` property.
+
+- The `url` property should be a string containing the base URL of the Stacks node you want to use.
+- The `fetch` property can be any (fetch)[https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API] compatible function.
+
+The following diffs show examples of how to migrate to the new pattern.
+
+```diff
+import { makeSTXTokenTransfer } from '@stacks/transactions';
+
+- import { StacksTestnet } from '@stacks/network';
++ import { STACKS_TESTNET } from '@stacks/transactions';
+
+const transaction = await makeSTXTokenTransfer({
+  // ...
+- network: new StacksTestnet(),
++ network: STACKS_TESTNET,
+});
+```
+
+> [!NOTE]
+> String literal network names are still supported.
+
+```diff
+const transaction = await makeSTXTokenTransfer({
+  // ...
+- network: new StacksTestnet(),
++ network: 'testnet',
+});
+```
+
+> [!NOTE]
+> Custom URLs and fetch functions are still supported via the `api` parameter.
+
+```diff
+const transaction = await makeSTXTokenTransfer({
+  // ...
+- network: new StacksTestnet({ url: "mynode-optional.com", fetchFn: myFetch }), // optional options
++ network: STACKS_TESTNET,
++ api: { url: "mynode-optional.com", fetch: myFetch } // optional params
+});
+```
+
 ## Stacks.js (&lt;=4.x.x) → (5.x.x)
 
 ### Breaking Changes

.vscode/launch.json

@@ -7,9 +7,7 @@
       "name": "Jest: auth",
       "cwd": "${workspaceFolder}/packages/auth",
       "program": "./node_modules/.bin/jest",
-      "args": [
-        "--runInBand"
-      ],
+      "args": ["--runInBand"],
       "console": "integratedTerminal"
     },
     {
@@ -18,9 +16,7 @@
       "name": "Jest: bns",
       "cwd": "${workspaceFolder}/packages/bns",
       "program": "./node_modules/.bin/jest",
-      "args": [
-        "--runInBand"
-      ],
+      "args": ["--runInBand"],
       "console": "integratedTerminal"
     },
     {
@@ -29,9 +25,7 @@
       "name": "Jest: cli",
       "cwd": "${workspaceFolder}/packages/cli",
       "program": "./node_modules/.bin/jest",
-      "args": [
-        "--runInBand"
-      ],
+      "args": ["--runInBand"],
       "console": "integratedTerminal"
     },
     {
@@ -40,9 +34,7 @@
       "name": "Jest: common",
       "cwd": "${workspaceFolder}/packages/common",
       "program": "./node_modules/.bin/jest",
-      "args": [
-        "--runInBand"
-      ],
+      "args": ["--runInBand"],
       "console": "integratedTerminal"
     },
     {
@@ -51,9 +43,7 @@
       "name": "Jest: encryption",
       "cwd": "${workspaceFolder}/packages/encryption",
       "program": "./node_modules/.bin/jest",
-      "args": [
-        "--runInBand"
-      ],
+      "args": ["--runInBand"],
       "console": "integratedTerminal"
     },
     {
@@ -62,20 +52,16 @@
       "name": "Jest: keychain",
       "cwd": "${workspaceFolder}/packages/keychain",
       "program": "./node_modules/.bin/jest",
-      "args": [
-        "--runInBand"
-      ],
+      "args": ["--runInBand"],
       "console": "integratedTerminal"
     },
     {
       "type": "node",
       "request": "launch",
-      "name": "Jest: network",
-      "cwd": "${workspaceFolder}/packages/network",
+      "name": "Jest: api",
+      "cwd": "${workspaceFolder}/packages/api",
       "program": "./node_modules/.bin/jest",
-      "args": [
-        "--runInBand"
-      ],
+      "args": ["--runInBand"],
       "console": "integratedTerminal"
     },
     {
@@ -84,9 +70,7 @@
       "name": "Jest: profile",
       "cwd": "${workspaceFolder}/packages/profile",
       "program": "./node_modules/.bin/jest",
-      "args": [
-        "--runInBand"
-      ],
+      "args": ["--runInBand"],
       "console": "integratedTerminal"
     },
     {
@@ -95,9 +79,7 @@
       "name": "Jest: stacking",
       "cwd": "${workspaceFolder}/packages/stacking",
       "program": "./node_modules/.bin/jest",
-      "args": [
-        "--runInBand"
-      ],
+      "args": ["--runInBand"],
       "console": "integratedTerminal"
     },
     {
@@ -106,9 +88,7 @@
       "name": "Jest: storage",
       "cwd": "${workspaceFolder}/packages/storage",
       "program": "./node_modules/.bin/jest",
-      "args": [
-        "--runInBand"
-      ],
+      "args": ["--runInBand"],
       "console": "integratedTerminal"
     },
     {
@@ -117,10 +97,8 @@
       "name": "Jest: transactions",
       "cwd": "${workspaceFolder}/packages/transactions",
       "program": "./node_modules/.bin/jest",
-      "args": [
-        "--runInBand"
-      ],
+      "args": ["--runInBand"],
       "console": "integratedTerminal"
-    },
+    }
   ]
 }

README.md

@@ -1,7 +1,5 @@
 # Stacks.js [![Test Action Badge](https://github.com/hirosystems/stacks.js/actions/workflows/tests.yml/badge.svg)](https://github.com/hirosystems/stacks.js/actions/workflows/tests.yml) [![Monorepo Version Label](https://img.shields.io/github/lerna-json/v/hirosystems/stacks.js?label=monorepo)](https://github.com/hirosystems/stacks.js/tree/main/packages)
 
-
-
 Welcome to the Stacks.js repository, your one-stop solution for working with the Stacks blockchain using JavaScript/TypeScript. This repository nests a collection of packages designed to provide you with the essential building blocks to work with the [Stacks blockchain](https://www.stacks.co/what-is-stacks) from JavaScript/TypeScript.
 
 ## Packages
@@ -20,7 +18,7 @@ For installation instructions and usage guidelines, refer to the respective `REA
 - [`@stacks/encryption`](https://github.com/hirosystems/stacks.js/tree/main/packages/encryption) Encryption functions used by stacks.js packages.
 - [`@stacks/auth`](https://github.com/hirosystems/stacks.js/tree/main/packages/auth) Construct and decode authentication requests for Stacks apps.
 - [`@stacks/profile`](https://github.com/hirosystems/stacks.js/tree/main/packages/profile) Functions for manipulating user profiles.
-- [`@stacks/network`](https://github.com/hirosystems/stacks.js/tree/main/packages/network) Network and API library for working with Stacks blockchain nodes.
+- [`@stacks/api`](https://github.com/hirosystems/stacks.js/tree/main/packages/api) Stacks API and node library for network operations.
 - [`@stacks/common`](https://github.com/hirosystems/stacks.js/tree/main/packages/common) Common utilities used by stacks.js packages.
 
 ### Native Smart Contract Interaction
@@ -45,9 +43,9 @@ To migrate your app from blockstack.js to Stacks.js follow the steps in the [mig
 
 If you encounter a bug or have a feature request, we encourage you to follow the steps below:
 
-1.  **Search for existing issues:** Before submitting a new issue, please search [existing and closed issues](../../issues) to check if a similar problem or feature request has already been reported.
-1.  **Open a new issue:** If it hasn't been addressed, please [open a new issue](../../issues/new/choose). Choose the appropriate issue template and provide as much detail as possible, including steps to reproduce the bug or a clear description of the requested feature.
-1.  **Evaluation SLA:** Our team reads and evaluates all the issues and pull requests. We are available Monday to Friday and we make our best effort to respond within 7 business days.
+1. **Search for existing issues:** Before submitting a new issue, please search [existing and closed issues](../../issues) to check if a similar problem or feature request has already been reported.
+1. **Open a new issue:** If it hasn't been addressed, please [open a new issue](../../issues/new/choose). Choose the appropriate issue template and provide as much detail as possible, including steps to reproduce the bug or a clear description of the requested feature.
+1. **Evaluation SLA:** Our team reads and evaluates all the issues and pull requests. We are available Monday to Friday and we make our best effort to respond within 7 business days.
 
 Please **do not** use the issue tracker for personal support requests or to ask for the status of a transaction. You'll find help at the [#support Discord channel](https://discord.gg/SK3DxdsP).
 
@@ -56,19 +54,19 @@ Please **do not** use the issue tracker for personal support requests or to ask
 Development of Stacks.js happens in the open on GitHub, and we are grateful to the community for contributing bug fixes and improvements. Read below to learn how you can take part in improving the Stacks.js.
 
 ### Code of Conduct
-Please read Stacks.js' [Code of Conduct](https://github.com/hirosystems/stacks.js/blob/main/CODE_OF_CONDUCT.md) since we expect project participants to adhere to it. 
+
+Please read Stacks.js' [Code of Conduct](https://github.com/hirosystems/stacks.js/blob/main/CODE_OF_CONDUCT.md) since we expect project participants to adhere to it.
 
 ### Contributing Guide
+
 Read our [contributing guide](https://github.com/hirosystems/stacks.js/blob/main/.github/CONTRIBUTING.md) to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes.
 
 ## Community
 
 Join our community and stay connected with the latest updates and discussions:
 
 - [Join our Discord community chat](https://discord.gg/ZQR6cyZC) to engage with other users, ask questions, and participate in discussions.
-
 - [Visit hiro.so](https://www.hiro.so/) for updates and subscribe to the mailing list.
-
 - Follow [Hiro on Twitter.](https://twitter.com/hirosystems)
 
 ## License

configs/webpack.config.js

@@ -54,12 +54,12 @@ module.exports = {
   resolve: {
     extensions: ['.ts', '.js'],
     alias: {
+      '@stacks/api': '@stacks/api/dist/esm',
       '@stacks/auth': '@stacks/auth/dist/esm',
       '@stacks/bns': '@stacks/bns/dist/esm',
       '@stacks/common': '@stacks/common/dist/esm',
       '@stacks/encryption': '@stacks/encryption/dist/esm',
       '@stacks/keychain': '@stacks/keychain/dist/esm',
-      '@stacks/network': '@stacks/network/dist/esm',
       '@stacks/profile': '@stacks/profile/dist/esm',
       '@stacks/stacking': '@stacks/stacking/dist/esm',
       '@stacks/storage': '@stacks/storage/dist/esm',