Add legacy safe-core-sdk migration guide (#291)

* update ethers docs * add singleton change to api-kit and protocol-kit update api-kit initialization update createTransaction use * Fix linting and typos * fix: broken links * update GelatoRelayKit breaking changes * improve parameter naming * fix linter reported issue * fix wording recommendations * highlight ethers.js v6 * add migration guides highlighting the major changes * fix typos * Apply suggestions from code review Co-authored-by: Tanay Pant <[email protected]> * add backticks to EthersAdapter * Apply suggestions from code review Co-authored-by: Tanay Pant <[email protected]> * set migrating guides below reference * add wording suggestions * Add safe-transaction-service migration guide * Add migration guide from legacy safe-core-sdk * Add types changes * remove auth-kit changes * fix linting issues * improve api-kit v2 migration * Add latest changes * Add missing type * fix typo * Apply suggestions from code review Co-authored-by: Tanay Pant <[email protected]> * add migration links * Update safe-core-sdk/protocol-kit/reference/migrating/v1.md Co-authored-by: Tanay Pant <[email protected]> * Reverse migration links order in SUMMARY --------- Co-authored-by: Daniel Somoza <[email protected]> Co-authored-by: Tanay Pant <[email protected]>
safe-global · Nov 30, 2023 · d393a62 · d393a62
1 parent 558747a
commit d393a62
Show file tree

Hide file tree

Showing 5 changed files with 247 additions and 5 deletions.
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -35,6 +35,7 @@
 * [Protocol Kit](safe-core-sdk/protocol-kit/README.md)
   * [Reference](safe-core-sdk/protocol-kit/reference/README.md)
     * [Migrating to v2](safe-core-sdk/protocol-kit/reference/migrating/v2.md)
+    * [Migrating to v1](safe-core-sdk/protocol-kit/reference/migrating/v1.md)
 
 * [Onramp Kit](safe-core-sdk/onramp-kit/README.md)
   * [Guides](safe-core-sdk/onramp-kit/guides/README.md)
@@ -54,6 +55,7 @@
 * [API Kit](safe-core-sdk/api-kit/README.md)
   * [Reference](safe-core-sdk/api-kit/reference/README.md)
     * [Migrating to v2](safe-core-sdk/api-kit/reference/migrating/v2.md)
+    * [Migrating to v1](safe-core-sdk/api-kit/reference/migrating/v1.md)
 
 
 ## Safe{Core} Protocol

diff --git a/safe-core-sdk/api-kit/reference/migrating/v1.md b/safe-core-sdk/api-kit/reference/migrating/v1.md
@@ -0,0 +1,114 @@
+# API Kit: Migrating from `safe-service-client`
+
+This guide references the major changes between `safe-service-client` and `api-kit` v1 to help those migrating an existing application.
+
+**Note:** Follow this guide before migrating to `api-kit` v2.
+
+After completing this guide, you can remove `@safe-global/safe-service-client` from your package.json`.
+
+## Adding the new dependency
+
+To add the API Kit to your project, run the following:
+
+```bash
+yarn add @safe-global/[email protected]
+```
+
+Change your initialization like this:
+
+```typescript
+// old
+import SafeServiceClient from '@safe-global/safe-service-client'
+
+const safeService = new SafeServiceClient({
+  txServiceUrl: 'https://your-transaction-service-url',
+  ethAdapter
+})
+
+// new
+import SafeApiKit from '@safe-global/api-kit'
+
+const apiKit = new SafeApiKit({
+  txServiceUrl: 'https://your-transaction-service-url',
+  ethAdapter
+})
+```
+
+## `getSafeDelegates()`
+
+The `getSafeDelegates` was updated to accept more filtering parameters. Now, it accepts an object with multiple properties instead of only the `safeAddress` parameter.
+
+```typescript
+const delegateConfig: GetSafeDelegateProps = {
+  safeAddress, // Optional
+  delegateAddress, // Optional
+  delegatorAddress, // Optional
+  label, // Optional
+  limit, // Optional
+  offset // Optional
+}
+const delegates: SafeDelegateListResponse = await apiKit.getSafeDelegates(delegateConfig)
+```
+
+## `addSafeDelegate()`
+
+Parameter object properties were updated as follows:
+
+```typescript
+// old
+const delegateConfig: SafeDelegateConfig = {
+  safe,
+  delegate,
+  label,
+  signer
+}
+await safeService.addSafeDelegate(delegateConfig)
+
+// new
+const delegateConfig: AddSafeDelegateProps = {
+  safeAddress, // Optional
+  delegateAddress,
+  delegatorAddress,
+  label,
+  signer
+}
+await apiKit.addSafeDelegate(delegateConfig)
+```
+
+## `removeAllSafeDelegates()`
+
+The method was deprecated and removed.
+
+## `removeSafeDelegate()`
+
+Parameter object properties were updated as follows:
+
+```typescript
+// old
+const delegateConfig: SafeDelegateDeleteConfig = {
+  safe,
+  delegate,
+  signer
+}
+await safeService.removeSafeDelegate(delegateConfig)
+
+// new
+const delegateConfig: DeleteSafeDelegateProps = {
+  delegateAddress,
+  delegatorAddress,
+  signer
+}
+await apiKit.removeSafeDelegate(delegateConfig)
+```
+
+## `getBalances()`
+
+The method was deprecated and removed.
+
+## `getUSDBalances()`
+
+The method was deprecated and removed.
+
+## `getCollectibles()`
+
+The method was deprecated and removed.
diff --git a/safe-core-sdk/api-kit/reference/migrating/v2.md b/safe-core-sdk/api-kit/reference/migrating/v2.md
@@ -8,10 +8,26 @@ It won't be necessary to specify a `txServiceUrl` in environments where Safe has
 
 ```js
 // old:
-constructor({ txServiceUrl, ethAdapter }: SafeApiKitConfig)
+import SafeApiKit from '@safe-global/api-kit'
+
+const apiKit = new SafeApiKit({
+  txServiceUrl: 'https://your-transaction-service-url',
+  ethAdapter
+})
 
 // new:
-constructor({ chainId, txServiceUrl? }: SafeApiKitConfig)
+import SafeApiKit from '@safe-global/api-kit'
+
+const chainId: bigint = 1n
+const apiKit = new SafeApiKit({
+  chainId
+})
+
+// or set a custom Transaction Service
+const apiKit = new SafeApiKit({
+  chainId,
+  txServiceUrl: 'https://your-transaction-service-url'
+})
 ```
 
 ## Use the route you prefer
@@ -23,11 +39,17 @@ Note that if you use a custom service running under `/api`, you will now need to
 ```js
 // old:
 const txServiceUrl = 'https://your-transaction-service-domain/'
-constructor({ txServiceUrl, ethAdapter }: SafeApiKitConfig)
-
+const apiKit = new SafeApiKit({
+  txServiceUrl,
+  ethAdapter
+})
 // new:
+const chainId: bigint = 1n
 const txServiceUrl = 'https://your-transaction-service-domain/api'
-constructor({ chainId, txServiceUrl? }: SafeApiKitConfig)
+const apiKit = new SafeApiKit({
+  chainId,
+  txServiceUrl
+})
 ```
 
 ## MasterCopy to Singleton

diff --git a/safe-core-sdk/protocol-kit/reference/migrating/v1.md b/safe-core-sdk/protocol-kit/reference/migrating/v1.md
@@ -0,0 +1,102 @@
+# Protocol Kit: Migrating from `safe-core-sdk`
+
+This guide references the major changes between `safe-core-sdk` and `protocol-kit` v1 to help those migrating an existing application.
+
+**Note:** Follow this guide before migrating to `protocol-kit` v2.
+
+You can remove `@safe-global/safe-core-sdk` from your `package.json` after completing this guide.
+
+## Adding the new dependency
+
+To add the Protocol Kit to your project, run the following:
+
+```bash
+yarn add @safe-global/[email protected]
+```
+
+If you use the types library, you will need to update to v2.3.0:
+
+```bash
+yarn add @safe-global/[email protected]
+```
+
+## `EthAdapter`
+
+### `EthersAdapter` (safe-ethers-lib)
+
+`EthersAdapter` isn't in a separate package anymore. Now, it's provided inside the `protocol-kit` package.
+
+**`protocol-kit v1` only supports `ethers v5`**
+
+```typescript
+// old
+import EthersAdapter from '@safe-global/safe-ethers-lib'
+
+// new
+import { EthersAdapter } from '@safe-global/protocol-kit'
+```
+
+After this change, you can remove `@safe-global/safe-ethers-lib` from your `package.json`.
+
+### `Web3Adapter` (safe-web3-lib)
+
+`Web3Adapter` isn't in a separate package anymore. Now, it's part of the `protocol-kit` package.
+
+**Note:** `protocol-kit` v1 only supports Web3.js v1.
+
+```typescript
+// old
+import Web3Adapter from '@safe-global/safe-web3-lib'
+
+// new
+import { Web3Adapter } from '@safe-global/protocol-kit'
+```
+
+After this change, you can remove `@safe-global/safe-web3-lib` from your `package.json`.
+
+### Type changes
+
+Type changes are affecting the web3 and ethers adapter libraries.
+
+`getSafeContract`, `getMultisendContract`, `getMultisendCallOnlyContract`, `getCompatibilityFallbackHandlerContract`, `getSafeProxyFactoryContract`, `getSignMessageLibContract` and `getCreateCallContract` don't need the `chainId` parameter anymore, they will use the chain set on the provider. Also, they return a `Promise` now.
+
+`estimateGas` now returns a `string` instead of a `number`.
+
+## `safeFactory.deploySafe()`
+
+`SafeDeploymentConfig` was simplified. If you were using a `saltNonce` you should set it like this:
+
+```typescript
+// old
+const safeAccountConfig: SafeAccountConfig = {
+  ...
+}
+const safeDeploymentConfig: SafeDeploymentConfig = { saltNonce }
+
+const safeSdk = await safeFactory.deploySafe({ safeAccountConfig, safeDeploymentConfig })
+
+// new
+const safeAccountConfig: SafeAccountConfig = {
+  ...
+}
+
+const saltNonce = '<YOUR_CUSTOM_VALUE>'
+
+const safeSdk = await safeFactory.deploySafe({ safeAccountConfig, saltNonce })
+```
+
+## `getAddress()`
+
+The `getAddress()` method now returns a `Promise`.
+
+```typescript
+// old
+const safeAddress = safeSdk.getAddress()
+
+// new
+const safeAddress = await protocolKit.getAddress()
+```
+
+## General type changes
+
+If you set `safeTxGas`, `baseGas`, or `gasPrice`, you must use the type `string` instead of `number`.
diff --git a/safe-core-sdk/protocol-kit/reference/migrating/v2.md b/safe-core-sdk/protocol-kit/reference/migrating/v2.md
@@ -2,6 +2,8 @@
 
 This guide references the major changes between v1 and v2 to help those migrating an existing app.
 
+**Note:** When upgrading to `protocol-kit` v2, it's necessary to upgrade to `safe-core-sdk-types` v3.
+
 ## MasterCopy to Singleton
 
 To avoid confusion between terms used as synonyms, we aligned all our code to use the word `singleton`.