From 8cf2e30c3d75ee42c85716df848b132d0ab28c6e Mon Sep 17 00:00:00 2001 From: janniks Date: Mon, 21 Oct 2024 17:45:34 +0200 Subject: [PATCH] docs: Update migration file --- .github/MIGRATION.md | 102 ++++++++++++++++++++++++------------------- 1 file changed, 58 insertions(+), 44 deletions(-) diff --git a/.github/MIGRATION.md b/.github/MIGRATION.md index 7d70ea1f8..eeb205f77 100644 --- a/.github/MIGRATION.md +++ b/.github/MIGRATION.md @@ -2,13 +2,12 @@ - [Stacks.js (\>=5.x.x) → (7.x.x)](#stacksjs-5xx--7xx) - [Breaking Changes](#breaking-changes) + - [Reducing Wrapper Types](#reducing-wrapper-types) - [Stacks Network](#stacks-network) - [Impacts](#impacts) - - [Fetch Methods](#fetch-methods) - - [Reducing Wrapper Types](#reducing-wrapper-types) - - [Stacks Network](#stacks-network-1) - [Clarity Representation](#clarity-representation) - [Post-conditions](#post-conditions) + - [Fetch Methods](#fetch-methods) - [`serialize` methods](#serialize-methods) - [Asset Helper Methods](#asset-helper-methods) - [CLI](#cli) @@ -47,6 +46,15 @@ - **Advanced:** Removes two's complement compatibilty from `intToBigInt` parser method. [Read more...](#advanced-signed-bigint) - **Advanced:** Refactorings and less visible updates. [Read more...](#advanced-refactorings) +### Reducing Wrapper Types + +With this release we are aiming to reduce unnecessary "wrapper" types, which are used in the internals of the codebase, but shouldn't be pushed onto the user/developer. + +This breaks the signatures of many functions: + +- `signMessageHashRsv`, `signWithKey` now return the message signature as a `string` directly. +- `nextSignature`, `nextVerification`, `publicKeyFromSignatureVrs`, `publicKeyFromSignatureRsv` now take in the message signature as a `string`. + ### Stacks Network From now on "network" objects are static (aka constants) and don't require instantiation. @@ -62,51 +70,26 @@ The `@stacks/network` package exports the following network objects: import { STACKS_MAINNET } from '@stacks/network'; import { STACKS_TESTNET } from '@stacks/network'; import { STACKS_DEVNET } from '@stacks/network'; -``` - -#### Impacts - -- @stacks/bns: `BnsContractAddress` was removed, since `.bootAddress` is now a part of the network objects. -- @stacks/transactions: `AddressVersion` was moved to `@stacks/network`. - -### Fetch Methods - -The following methods were renamed: - -- `estimateFee` → `fetchFeeEstimate` -- `estimateTransfer` → `fetchFeeEstimateTransfer` -- `estimateTransaction` → `fetchFeeEstimateTransaction` -- `getAbi` → `fetchAbi` -- `getNonce` → `fetchNonce` -- `getContractMapEntry` → `fetchContractMapEntry` -- `callReadOnlyFunction` → `fetchCallReadOnlyFunction` - -`broadcastTransaction` wasn't renamed to highlight the uniqueness of the method. -Namely, the node/API it is sent to will "broadcast" the transaction to the mempool. - -### Reducing Wrapper Types - -With this release we are aiming to reduce unnecessary "wrapper" types, which are used in the internals of the codebase, but shouldn't be pushed onto the user/developer. - -This breaks the signatures of many functions: - -- `signMessageHashRsv`, `signWithKey` now return the message signature as a `string` directly. -- `nextSignature`, `nextVerification`, `publicKeyFromSignatureVrs`, `publicKeyFromSignatureRsv` now take in the message signature as a `string`. - -### Stacks Network -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'; +console.log(STACKS_MAINNET); +// { +// chainId: 1, +// transactionVersion: 0, +// peerNetworkId: 385875968, +// magicBytes: 'X2', +// bootAddress: 'SP000000000000000000002Q6VF78', +// addressVersion: { singleSig: 22, multiSig: 20 }, +// client: { baseUrl: 'https://api.mainnet.hiro.so' } +// } ``` -After importing the network object (e.g. `STACKS_MAINNET` here), you can use it in other functions like so: +After importing the network object (e.g. `STACKS_MAINNET` here), you can use it in other functions as the `network` parameter. +Most of the time it's easier to just set the `network` parameter to a string literal (`'mainnet'`, `'testnet'`, or `'devnet'`). - +As part of the network object, the `client` property was added. +This contains a `baseUrl` property and can optionally contain a `fetch` property. -For easing the transition, the functions which depended on a network instance now accept an `client` parameter. +For easing the transition, the functions which depended on a network instance now accept an optional `client` parameter. The `client` parameter can be any object containing a `baseUrl` and `fetch` property. - The `baseUrl` property should be a string containing the base URL of the Stacks node you want to use. @@ -139,7 +122,7 @@ const transaction = await makeSTXTokenTransfer({ ``` > [!NOTE] -> Custom URLs and fetch functions are still supported via the `client` parameter. +> Custom URLs and fetch functions are still supported via the `client` parameter or via `network.client`. ```diff const transaction = await makeSTXTokenTransfer({ @@ -150,6 +133,22 @@ const transaction = await makeSTXTokenTransfer({ }); ``` +```diff +const transaction = await makeSTXTokenTransfer({ + // ... +- network: new StacksTestnet({ url: "mynode-optional.com", fetchFn: myFetch }), // optional options ++ network: { ++ ...STACKS_TESTNET, ++ client: { baseUrl: "mynode-optional.com", fetch: myFetch } // optional params ++ }, +}); +``` + +#### Impacts + +- @stacks/bns: `BnsContractAddress` was removed, since `.bootAddress` is now a part of the network objects. +- @stacks/transactions: `AddressVersion` was moved to `@stacks/network`. + ### Clarity Representation The `ClarityType` enum was replaced by a readable version. @@ -213,6 +212,21 @@ const nftPostCondition: NonFungiblePostCondition = { }; ``` +### Fetch Methods + +The following methods were renamed: + +- `estimateFee` → `fetchFeeEstimate` +- `estimateTransfer` → `fetchFeeEstimateTransfer` +- `estimateTransaction` → `fetchFeeEstimateTransaction` +- `getAbi` → `fetchAbi` +- `getNonce` → `fetchNonce` +- `getContractMapEntry` → `fetchContractMapEntry` +- `callReadOnlyFunction` → `fetchCallReadOnlyFunction` + +`broadcastTransaction` wasn't renamed to highlight the uniqueness of the method. +Namely, the node/API it is sent to will "broadcast" the transaction to the mempool. + ### `serialize` methods Existing methods now take or return **hex-encoded strings** _instead_ of `Uint8Array`s.