docs: Add multichain Safe deployments guide (#617)

* Add new safe-deployment guides * Add installation snippet to align with our new documentation format * fix comment in the import step * update signer instantiation details * update 'predictedSafe' property in Protocol Kit initialization * Update pages/sdk/protocol-kit/guides/safe-deployment/deploy-safe.mdx Co-authored-by: Daniel <[email protected]> * Update pages/sdk/protocol-kit/guides/safe-deployment/deploy-safe.mdx Co-authored-by: Yago Pérez Vázquez <[email protected]> * Update pages/sdk/protocol-kit/guides/safe-deployment/deploy-safe.mdx Co-authored-by: Yago Pérez Vázquez <[email protected]> * Update pages/sdk/protocol-kit/guides/safe-deployment/deploy-safe.mdx Co-authored-by: Yago Pérez Vázquez <[email protected]> * Update pages/sdk/protocol-kit/guides/safe-deployment/deploy-safe.mdx Co-authored-by: Yago Pérez Vázquez <[email protected]> * Update pages/sdk/protocol-kit/guides/safe-deployment/deploy-safe.mdx Co-authored-by: Yago Pérez Vázquez <[email protected]> * Update pages/sdk/protocol-kit/guides/safe-deployment/address-replication.mdx Co-authored-by: Daniel <[email protected]> * Update pages/sdk/protocol-kit/guides/safe-deployment/deploy-safe.mdx Co-authored-by: Daniel <[email protected]> * Update pages/sdk/protocol-kit/guides/safe-deployment/address-replication.mdx Co-authored-by: Daniel <[email protected]> * updated Safe import section * Update pages/sdk/protocol-kit/guides/safe-deployment/address-replication.mdx Co-authored-by: Yago Pérez Vázquez <[email protected]> * fix: disable Vale in code snippets * fix: move some Vale config entries to correct lines * chore: fix wording and style about initializaton * Fixes in Deploy Safe guide * Adjust multichain deployment guide * Adjustments in Safe deployment guide * Rename guides * List deployment guides in the overview * Fix vale * Update links --------- Co-authored-by: Daniel <[email protected]> Co-authored-by: Yago Pérez Vázquez <[email protected]> Co-authored-by: Germán Martínez <[email protected]>
safe-global · Oct 31, 2024 · c564a36 · c564a36
1 parent fb40d5e
commit c564a36
Show file tree

Hide file tree

Showing 5 changed files with 369 additions and 1 deletion.
diff --git a/.github/styles/config/vocabularies/default/accept.txt b/.github/styles/config/vocabularies/default/accept.txt
@@ -37,6 +37,7 @@
 [Mm]ainnet
 [Mm]iddleware
 [Mm]onerium
+[Mm]ultichain
 [Mm]ultisig
 [Mm]ultisend
 [Nn]extra
@@ -263,7 +264,6 @@ maxWidth
 mempool
 messageHash
 monorepo
-multichain
 npm
 onboarding
 onchain

diff --git a/pages/sdk/protocol-kit.mdx b/pages/sdk/protocol-kit.mdx
@@ -14,6 +14,8 @@ The Protocol Kit enables developers to interact with [Safe Smart Accounts](https
 </Grid>
 
 The following guides show how to use the Protocol Kit and integrate it into your project:
+- [Safe deployment](./protocol-kit/guides/safe-deployment.mdx)
+- [Multichain Safe deployment](./protocol-kit/guides/multichain-safe-deployment.mdx)
 - [Execute transactions](./protocol-kit/guides/execute-transactions.mdx)
 - [Transactions signatures](./protocol-kit/guides/signatures/transactions.mdx)
 - [Message signatures](./protocol-kit/guides/signatures/messages.mdx)

diff --git a/pages/sdk/protocol-kit/guides/_meta.json b/pages/sdk/protocol-kit/guides/_meta.json
@@ -1,4 +1,6 @@
 {
+  "safe-deployment": "Safe deployment",
+  "multichain-safe-deployment": "Multichain Safe deployment",
   "execute-transactions": "Execute transactions",
   "signatures": "Signatures",
   "migrate-to-v1": "Migrate to v1",

diff --git a/pages/sdk/protocol-kit/guides/multichain-safe-deployment.mdx b/pages/sdk/protocol-kit/guides/multichain-safe-deployment.mdx
@@ -0,0 +1,209 @@
+import { Steps } from 'nextra/components'
+
+# Multichain Safe Deployment
+
+This guide will teach you how to replicate a Safe address across different chains using the Protocol Kit. This process includes initializing the Protocol Kit, configuring the Safes to deploy, predicting its address on different chains, and executing the deployment transactions.
+
+## Prerequisites
+
+- [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+
+## Install dependencies
+
+First, you need to install the Protocol Kit.
+
+{/* <!-- vale off --> */}
+
+```bash
+pnpm add @safe-global/protocol-kit viem
+```
+
+{/* <!-- vale on --> */}
+
+## Steps
+
+<Steps>
+
+  ### Imports
+
+  Here are all the necessary imports for this guide.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  import Safe, {
+    PredictedSafeProps,
+    SafeAccountConfig,
+    SafeDeploymentConfig
+  } from '@safe-global/protocol-kit'
+  import { waitForTransactionReceipt } from 'viem/actions'
+  import { gnosisChiado, sepolia } from 'viem/chains'
+  ```
+
+  {/* <!-- vale on --> */}
+
+  ### Create a signer
+
+  You need a signer to instantiate the Protocol Kit. This example uses a private key to obtain a signer, but other [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) compatible signers are also supported. For detailed information about signers, please refer to the [Protocol Kit reference](../../../reference-sdk-protocol-kit/overview.md).
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const SIGNER_PRIVATE_KEY = // ...
+  ```
+
+  {/* <!-- vale on --> */}
+
+  ### Configure the Safe deployment
+
+  Define the [`predictedSafe`](../../../reference-sdk-protocol-kit/initialization/init.mdx#predictedsafe-optional) object with the configuration for all the Safe accounts you will deploy. Check the reference to learn about all the different configuration options.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const safeAccountConfig: SafeAccountConfig = {
+    owners: ['0x...', '0x...', '0x...'],
+    threshold: 2
+    // More optional properties
+  }
+
+  const predictedSafe: PredictedSafeProps = {
+    safeAccountConfig
+    // More optional properties
+  }
+  ```
+
+  {/* <!-- vale on --> */}
+
+  ### Initialize the Protocol Kit
+
+  Initialize an instance of the Protocol Kit for each network where you want to deploy a new Safe smart account by calling the [`init`](../../../reference-sdk-protocol-kit/initialization/init.mdx) method. Pass the `provider` with its corresponding value depending on the network, the `signer` executing the deployment, and the [`predictedSafe`](../../../reference-sdk-protocol-kit/initialization/init.mdx#predictedsafe-optional) with the Safe account configuration.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const protocolKitSepolia = await Safe.init({
+    provider: sepolia.rpcUrls.default.http[0],
+    signer: SIGNER_PRIVATE_KEY,
+    predictedSafe
+  })
+
+  const protocolKitChiado = await Safe.init({
+    provider: gnosisChiado.rpcUrls.default.http[0],
+    signer: PRIVATE_KEY,
+    predictedSafe
+  })
+  ```
+
+  {/* <!-- vale on --> */}
+
+  ### Predict the Safe addresses
+
+  You can predict the Safe addresses by calling the [`getAddress`](../../../reference-sdk-protocol-kit/safe-info/getaddress.mdx) method from each Protocol Kit instance and ensure that the result addresses are the same.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const sepoliaPredictedSafeAddress = await protocolKitSepolia.getAddress()
+  const chiadoPredictedSafeAddress = await protocolKitChiado.getAddress()
+  ```
+
+  {/* <!-- vale on --> */}
+
+  ### Deployment on Sepolia
+
+  Create the deployment transaction to deploy a new Safe account in Sepolia by calling the [`createSafeDeploymentTransaction`](../../../reference-sdk-protocol-kit/deployment/createsafedeploymenttransaction.mdx) method.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const sepoliaDeploymentTransaction =
+    await protocolKitSepolia.createSafeDeploymentTransaction()
+  ```
+
+  {/* <!-- vale on --> */}
+
+  Call the `sendTransaction` method from your Sepolia client instance and wait for the transaction to be executed.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const sepoliaClient =
+    await protocolKitSepolia.getSafeProvider().getExternalSigner()
+
+  const transactionHashSepolia = await sepoliaClient!.sendTransaction({
+    to: sepoliaDeploymentTransaction.to,
+    value: BigInt(sepoliaDeploymentTransaction.value),
+    data: sepoliaDeploymentTransaction.data as `0x${string}`,
+    chain: sepolia
+  })
+
+  await waitForTransactionReceipt(
+    sepoliaClient!,
+    { hash: transactionHashSepolia }
+  )
+  ```
+
+  {/* <!-- vale on --> */}
+
+  Once the deployment transaction is executed, connect the new Safe address to the Protocol Kit instance by calling the [`connect`](../../../reference-sdk-protocol-kit/initialization/connect.mdx) method.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const newProtocolKitSepolia = await protocolKitSepolia.connect({
+    safeAddress: sepoliaPredictedSafeAddress
+  })
+
+  const isSepoliaSafeDeployed = await newProtocolKitSepolia.isSafeDeployed() // True
+  const sepoliaDeployedSafeAddress = await newProtocolKitSepolia.getAddress()
+  ```
+
+  {/* <!-- vale on --> */}
+
+  If everything went well, `isSepoliaSafeDeployed` should be `true`, and the `sepoliaDeployedSafeAddress` should equal the `sepoliaPredictedSafeAddress`.
+
+  ### Deployment on Chiado
+
+  Repeat the same steps to deploy a Safe with the same configuration on Chiado testnet.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const chiadoDeploymentTransaction =
+    await protocolKitChiado.createSafeDeploymentTransaction()
+
+  const chiadoClient =
+    await protocolKitChiado.getSafeProvider().getExternalSigner()
+
+  const transactionHashChiado = await chiadoClient!.sendTransaction({
+    to: chiadoDeploymentTransaction.to,
+    value: BigInt(chiadoDeploymentTransaction.value),
+    data: chiadoDeploymentTransaction.data as `0x${string}`,
+    chain: gnosisChiado
+  })
+
+  await waitForTransactionReceipt(
+    chiadoClient!,
+    { hash: transactionHashChiado }
+  )
+
+  const newProtocolKitChiado = await protocolKitChiado.connect({
+    safeAddress: chiadoPredictedSafeAddress
+  })
+
+  const isChiadoSafeDeployed = await newProtocolKitChiado.isSafeDeployed() // True
+  const chiadoDeployedSafeAddress = await newProtocolKitChiado.getAddress()
+  ```
+
+  {/* <!-- vale on --> */}
+
+  If everything went well, `isChiadoSafeDeployed` should be `true`, and the `chiadoDeployedSafeAddress` should equal the `chiadoPredictedSafeAddress`.
+
+  In addition, `chiadoDeployedSafeAddress` and `sepoliaDeployedSafeAddress` should have the same value.
+
+</Steps>
+
+## Recap and further reading
+
+After following this guide, you are able to deploy multiple Safe accounts with the same address on different chains using the Protocol Kit.
diff --git a/pages/sdk/protocol-kit/guides/safe-deployment.mdx b/pages/sdk/protocol-kit/guides/safe-deployment.mdx
@@ -0,0 +1,155 @@
+import { Steps } from 'nextra/components'
+
+# Safe Deployment
+
+This guide will teach you how to deploy a new Safe using the Protocol Kit. This process includes initializing the Protocol Kit, setting up your Safe configuration, and executing the deployment.
+
+For more detailed information, see the [Protocol Kit Reference](../../../reference-sdk-protocol-kit/overview.mdx).
+
+## Prerequisites
+
+- [Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+
+## Install dependencies
+
+First, you need to install some dependencies.
+
+{/* <!-- vale off --> */}
+
+```bash
+pnpm add @safe-global/protocol-kit viem
+```
+
+{/* <!-- vale on --> */}
+
+## Steps
+
+<Steps>
+
+  ### Imports
+
+  Here are all the necessary imports for this guide.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  import Safe, {
+    PredictedSafeProps,
+    SafeAccountConfig,
+    SafeDeploymentConfig
+  } from '@safe-global/protocol-kit'
+  import { sepolia } from 'viem/chains'
+  ```
+
+  {/* <!-- vale on --> */}
+
+  ### Create a signer
+
+  You need a signer to instantiate the Protocol Kit. This example uses a private key to obtain a signer, but [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) compatible signers are also supported. For detailed information about signers, please refer to the [Protocol Kit reference](../../../reference-sdk-protocol-kit/overview.md).
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const SIGNER_PRIVATE_KEY = // ...
+  ```
+
+  {/* <!-- vale on --> */}
+
+  ### Initialize the Protocol Kit
+
+  Initialize an instance of the Protocol Kit for each network where you want to deploy a new Safe smart account by calling the [`init`](../../../reference-sdk-protocol-kit/initialization/init.mdx) method. Pass the `provider` with its corresponding value depending on the network, the `signer` executing the deployment, and the [`predictedSafe`](../../../reference-sdk-protocol-kit/initialization/init.mdx#predictedsafe-optional) with the Safe account configuration.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const safeAccountConfig: SafeAccountConfig = {
+    owners: ['0x...', '0x...', '0x...'],
+    threshold: 2
+    // More optional properties
+  }
+
+  const predictedSafe: PredictedSafeProps = {
+    safeAccountConfig
+    // More optional properties
+  }
+
+  const protocolKit = await Safe.init({
+    provider: sepolia.rpcUrls.default.http[0],
+    signer: SIGNER_PRIVATE_KEY,
+    predictedSafe
+  })
+  ```
+
+  {/* <!-- vale on --> */}
+
+  ### Predict the Safe address
+
+  You can predict the Safe address using the [`getAddress`](../../../reference-sdk-protocol-kit/safe-info/getaddress.mdx) method in the Protocol Kit.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const safeAddress = await protocolKit.getAddress()
+  ```
+
+  {/* <!-- vale on --> */}
+
+  ### Create the deployment transaction
+
+  Create the deployment transaction to deploy a new Safe smart account by calling the [`createSafeDeploymentTransaction`](../../../reference-sdk-protocol-kit/deployment/createsafedeploymenttransaction.mdx) method.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const deploymentTransaction = await protocolKit.createSafeDeploymentTransaction()
+  ```
+
+  {/* <!-- vale on --> */}
+
+  ### Execute the deployment transaction
+
+  Once the deployment transaction object is ready, execute it using the provided signer or your preferred external Ethereum client.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const client = await protocolKit.getSafeProvider().getExternalSigner()
+
+  const transactionHash = await client.sendTransaction({
+    to: deploymentTransaction.to,
+    value: BigInt(deploymentTransaction.value),
+    data: deploymentTransaction.data as `0x${string}`,
+    chain: sepolia
+  })
+
+  const transactionReceipt = await client.waitForTransactionReceipt({
+    hash: transactionHash
+  })
+  ```
+
+  {/* <!-- vale on --> */}
+
+  ### Reinitialize the Protocol Kit
+
+  Once the deployment transaction is executed, connect the new Safe address to the Protocol Kit instance by calling the [`connect`](../../../reference-sdk-protocol-kit/initialization/connect.mdx) method.
+
+  {/* <!-- vale off --> */}
+
+  ```typescript
+  const newProtocolKit = await protocolKit.connect({
+    safeAddress
+  })
+
+  const isSafeDeployed = await newProtocolKit.isSafeDeployed() // True
+  const safeAddress = await newProtocolKit.getAddress()
+  const safeOwners = await newProtocolKit.getOwners()
+  const safeThreshold = await newProtocolKit.getThreshold()
+  ```
+
+  {/* <!-- vale on --> */}
+
+</Steps>
+
+## Recap and further reading
+
+After following this guide, you are able to deploy new Safe smart accounts with the Protocol Kit.