feat: Improve playgrounds information (safe-global#1175)

* Improve README's

* Add env vars info

Author: yagopv

README.md

@@ -46,7 +46,7 @@ If you are interested in contributing, please read the [Contributing Guidelines]
 
 ## Playground
 
-This project includes a [playground](https://github.com/safe-global/safe-core-sdk/tree/main/playground/README.md) with a few scripts that can be used as a starting point to use the Safe{Core} SDK.
+This project includes a [playground](https://github.com/safe-global/safe-core-sdk/tree/main/playground/README.md) with a few scripts that can be used as a starting point to use the Safe{Core} SDK. These scripts contain valuable snippets that demonstrate various Safe features. They serve as a useful learning tool or starting point for implementing these features in your application.
 
 ## License
 

playground/README.md

@@ -9,7 +9,12 @@ yarn install
 yarn build
 ```
 
-Update the config inside the scripts you want to execute and run the following commands for each of them.
+Update the config inside the scripts you want to execute and run the following commands for each of them. There are 2 ways to configure the input parameters of the scripts:
+
+- Environment files can be found in each folder with the required configuration. In this case, rename the `.env-sample` file to `.env` and update the values according to the comments inside `.env-sample`.
+- Set the values directly in the script file.
+
+### `protocol-kit`
 
 #### Deploy a Safe
 
@@ -19,9 +24,51 @@ This script allows to deploy a new Safe account with any given configuration (nu
 yarn play deploy-safe
 ```
 
+#### Generate a custom Safe address
+
+This script shows how to generate a Safe address based on some custom config parameters. The Safe account address is deterministic and can be calculated based on the signers and threshold. This is useful for counterfactual deployments or multi-chain Safe accounts scenarios:
+
+```bash
+yarn play generate-safe-address
+```
+
+#### Estimate gas
+
+Showcase how to estimate the `gas` (The complete transaction gas cost) and `safeTxGas` (The concrete Safe contracts calls gas cost) for a transaction:
+
+```bash
+yarn play estimate-gas
+```
+
+#### Create and execute a transaction
+
+This script allows you to create and execute a transaction. It demonstrates the typical flow for a Safe transaction using the `protocol-kit`, including how to create, sign, and execute a transaction.
+
+```bash
+yarn play create-and-execute-transaction
+```
+
+#### Replicate Safe addresses
+
+This script demonstrates how to obtain the same Safe address across different networks. This is useful when you want to deploy a Safe account on another network while retaining the same Safe account address:
+
+```bash
+yarn play replicate-safe-address
+```
+
+#### Validate signatures
+
+This script shows how to validate the signatures of a Safe message using the `protocol-kit`:
+
+```bash
+yarn play validate-signatures
+```
+
+### `api-kit`
+
 #### Propose a transaction
 
-This script allows a signer of a Safe to share a transaction with the other signers by submitting it to the Safe Transaction Service:
+This script allows a signer of a Safe to share a transaction with the other signers by submitting it to the Safe Transaction Service first:
 
 ```bash
 yarn play propose-transaction
@@ -43,22 +90,126 @@ Once there are enough signatures collected for a given transaction in the Safe T
 yarn play execute-transaction
 ```
 
+### `relay-kit`
+
+#### Send User Operation using an existing Safe
+
+This script showcases how to create a Safe Operation from a batch of transactions, sign it and send to the bundler as an User Operation:
+
+```bash
+yarn play userop
+```
+
+#### Send User Operation with a non-existent Safe account
+
+This script demonstrates how to create a Safe Operation from a batch of transactions, sign it and send to the bundler as an User Operation for a non-existent Safe account:
+
+```bash
+yarn play userop-counterfactual
+```
+
+#### Send User Operation using an existing Safe and an ERC20 Paymaster
+
+This script showcases how to create a Safe Operation from a batch of transactions, sign it and send to the bundler as an User Operation. The User Operation gas costs will be covered with ERC20 tokens by using a paymaster:
+
+```bash
+yarn play userop-erc20-paymaster
+```
+
+#### Send User Operation using an ERC20 Paymaster with a non-existent Safe account
+
+This script showcases how to create a Safe Operation from a batch of transactions, sign it and send to the bundler as an User Operation for a non-existent Safe account. The User Operation gas costs will be covered with ERC20 tokens by using a paymaster:
+
+```bash
+yarn play userop-erc20-paymaster-counterfactual
+```
+
+#### Send User Operation using an existing Safe and a verifying Paymaster to sponsor the operation
+
+This script showcases how to create a Safe Operation from a batch of transactions, sign it and send to the bundler. The User Operation will be sponsored by using a Paymaster:
+
+```bash
+yarn play userop-verifying-paymaster
+```
+
+#### Send User Operation using a verifying Paymaster tp sponsor the operations with a non-existent Safe account
+
+This script demonstrates how to create a Safe Operation from a batch of transactions, sign it and send to the bundler for a non-existent Safe account. The User Operation will be sponsored by using a Paymaster:
+
+```bash
+yarn play userop-verifying-paymaster-counterfactual
+```
+
+#### Execute User Operations in parallel
+
+This script showcases how to execute multiple User Operations in parallel by using custom nonces:
+
+```bash
+yarn play userop-parallel-execution
+```
+
+#### Api kit interoperability
+
+This script shows how to create a Safe Operation and store it using the Safe Transaction Service. This process orchestrates signatures from additional owners before bundle the User Operation and send it to provider bundler services:
+
+```bash
+yarn play userop-api-kit-interoperability
+```
+
+#### Relay a transaction using Gelato
+
 In case you want to execute the transaction via a transaction relay, this script allows to do that, where the fees are extracted from the Safe balance:
 
 ```bash
-yarn play relay-paid-transaction
+yarn play gelato-paid-transaction
 ```
 
+#### Relay an sponsored transaction using Gelato
+
 In case you want to execute the transaction via a transaction relay, this script allows to to that, where the fees are extracted from a third party account balance that sponsors the transaction:
 
 ```bash
-yarn play relay-sponsored-transaction
+yarn play gelato-sponsored-transaction
 ```
 
-#### Generate a custom Safe address
+### `sdk-starter-kit`
+
+#### Create and execute a transaction
 
-This script allows to find the right `saltNonce` to generate a vanity Safe address with any given configuration:
+This script demonstrates how to use the `sdk-starter-kit` to create, sign, and execute a transaction and deploy the Safe account if it does not exist. Internally it use the Safe Transaction Service to propose and confirm the transactions in case more than one owner signature is required:
 
 ```bash
-yarn play generate-safe-address
+yarn play send-transactions
+```
+
+#### Create and execute Safe Operations
+
+This script demonstrates how to use the `sdk-starter-kit` to create, sign, and execute a Safe Operation and deploy the Safe account if it does not exist. Internally it use the Safe Transaction Service to propose and confirm the Safe Operations in case more than one owner signature is required:
+
+```bash
+yarn play send-safe-operation
+```
+
+#### Create and execute on-chain messages
+
+This script demonstrates how to use the `sdk-starter-kit` to create, sign, and execute on-chain messages and deploy the Safe account if it does not exist. Internally it use the Safe Transaction Service to propose and confirm the on-chain messages (that are basically regular transactions) in case more than one owner signature is required:
+
+```bash
+yarn play send-on-chain-message
+```
+
+#### Create and execute off-chain messages
+
+This script demonstrates how to use the `sdk-starter-kit` to create, sign, and execute off-chain messages and deploy the Safe account if it does not exist. Internally it use the Safe Transaction Service to propose and confirm the off-chain messages in case more than one owner signature is required:
+
+```bash
+yarn play send-off-chain-message
+```
+
+#### Setup Safe account owners
+
+This script demonstrates how to use the `sdk-starter-kit` to setup Safe accounts with different owner configurations
+
+```bash
+yarn play owner-management
 ```

playground/api-kit/confirm-transaction.ts

@@ -11,6 +11,7 @@ interface Config {
   SAFE_TX_HASH: string
 }
 
+// Adjust the configuration with your own input parameters before running the script
 const config: Config = {
   CHAIN_ID: 11155111n,
   RPC_URL: 'https://sepolia.gateway.tenderly.co',

playground/api-kit/execute-transaction.ts

@@ -13,6 +13,7 @@ interface Config {
   SAFE_TX_HASH: string
 }
 
+// Adjust the configuration with your own input parameters before running the script
 const config: Config = {
   CHAIN_ID: 11155111n,
   RPC_URL: 'https://sepolia.gateway.tenderly.co',

playground/api-kit/propose-transaction.ts

@@ -11,6 +11,7 @@ interface Config {
   SAFE_ADDRESS: string
 }
 
+// Adjust the configuration with your own input parameters before running the script
 const config: Config = {
   CHAIN_ID: 11155111n,
   RPC_URL: 'https://sepolia.gateway.tenderly.co',

playground/protocol-kit/create-execute-transaction.ts

@@ -17,6 +17,7 @@ interface Config {
   SAFE_ADDRESS: string
 }
 
+// Adjust the configuration with your own input parameters before running the script
 const config: Config = {
   RPC_URL: 'https://sepolia.gateway.tenderly.co',
   SIGNER_ADDRESS_PRIVATE_KEY: SIGNER_ADDRESS_PRIVATE_KEY!,

playground/protocol-kit/deploy-safe.ts

@@ -20,6 +20,7 @@ interface Config {
   }
 }
 
+// Adjust the configuration with your own input parameters before running the script
 const config: Config = {
   RPC_URL: sepolia.rpcUrls.default.http[0],
   DEPLOYER_ADDRESS_PRIVATE_KEY: '<DEPLOYER_ADDRESS_PRIVATE_KEY>',

playground/protocol-kit/estimate-gas.ts

@@ -2,6 +2,7 @@ import Safe, { estimateSafeTxGas } from '@safe-global/protocol-kit'
 import { Chain, gnosis, arbitrum, polygon } from 'viem/chains'
 import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
 
+// Adjust the configuration with your own input parameters before running the script
 const config = {
   SAFE_ADDRESS: '<SAFE_ADDRESS>',
   chain: gnosis // Add the viem chain where the SAFE_ADDRESS is deployed (gnosis, arbitrum, polygon, etc.)

playground/protocol-kit/generate-safe-address.ts

@@ -8,6 +8,7 @@ import { SafeVersion } from '@safe-global/types-kit'
 
 // This script can be used to generate a custom Safe address
 
+// Adjust the configuration with your own input parameters before running the script
 const config: Config = {
   // REQUIRED PARAMETERS
   owners: ['0x680cde08860141F9D223cE4E620B10Cd6741037E'],

playground/protocol-kit/replicate-address.ts

@@ -22,6 +22,7 @@ import {
 // This file can be used to play around with the Safe Core SDK
 
 // Safe config to be replicated in different chains
+// Adjust the configuration with your own input parameters before running the script
 const safeAccountConfig: SafeAccountConfig = {
   owners: ['0x0Ee26C4481485AC64BfFf2bdCaA21EdAeCEcdCa9'],
   threshold: 1

playground/protocol-kit/validate-signatures.ts

@@ -11,6 +11,7 @@ interface Config {
   SIGNER_SAFE_ADDRESS: string
 }
 
+// Adjust the configuration with your own input parameters before running the script
 // To run this script, you need a Safe with the following configuration
 // - 3/3 Safe with 3 owners and threshold 3
 //   - Owner 1: public address from OWNER1_PRIVATE_KEY

playground/relay-kit/.env-sample

@@ -1,12 +1,15 @@
-# Private key of the account used to transfer funds. DEpending on the playground this account should have ETH and/or Test Token
-# PIM token can be minted on the Pimlico Dashboard (https://dashboard.pimlico.io/test-erc20-faucet) and can be used for the test transfers and the ERC-20 Paymaster playgrounds
-# The derived address will be the Safe owner when using the counterfactual deployment
+# Private key of the account used to transfer funds. Depending on the playground this account should have ETH and/or Test Token (PIM tokens)
+# PIM tokens can be minted on the Pimlico Dashboard (https://dashboard.pimlico.io/test-erc20-faucet) and can be used for the test transfers and the ERC-20 Paymaster playgrounds
+# The derived address will be the Safe owner when using the counterfactual deployment and you should send the test tokens to this address in case the playground requires them
 PRIVATE_KEY=
-# Safe address when using the playgrounds where Safe already exists
+# Safe address to use with the playgrounds where Safe must already exist
 SAFE_ADDRESS=0x...
+# Set the preferred RPC url
 RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
+# Set the chain ID where the playgrounds will be used
 CHAIN_ID=11155111
-# You can get Bundler and Paymaster URL's from your provider's dashboard
+# You can get the bundler and paymaster URL's from your provider's dashboard
 BUNDLER_URL=
 PAYMASTER_URL=
+# Set the sponsor policy in case you are using one to test the sponsor user operations related playgrounds
 SPONSORSHIP_POLICY_ID=

playground/relay-kit/userop-counterfactual.ts

@@ -6,6 +6,8 @@ import { privateKeyToAccount } from 'viem/accounts'
 
 dotenv.config({ path: './playground/relay-kit/.env' })
 
+// Load environment variables from ./.env file
+// Follow .env-sample as an example to create your own file
 const { PRIVATE_KEY, RPC_URL = '', CHAIN_ID = '', BUNDLER_URL = '' } = process.env
 
 // PIM test token contract address

playground/relay-kit/userop-erc20-paymaster-counterfactual.ts

@@ -5,6 +5,8 @@ import { privateKeyToAccount } from 'viem/accounts'
 
 dotenv.config({ path: './playground/relay-kit/.env' })
 
+// Load environment variables from ./.env file
+// Follow .env-sample as an example to create your own file
 const { PRIVATE_KEY, RPC_URL = '', CHAIN_ID = '', BUNDLER_URL = '' } = process.env
 
 // Paymaster addresses

playground/relay-kit/userop-erc20-paymaster.ts

@@ -4,6 +4,8 @@ import { waitForOperationToFinish, setup4337Playground } from '../utils'
 
 dotenv.config({ path: './playground/relay-kit/.env' })
 
+// Load environment variables from ./.env file
+// Follow .env-sample as an example to create your own file
 const {
   PRIVATE_KEY,
   SAFE_ADDRESS = '0x',

playground/relay-kit/userop-parallel-execution.ts

@@ -4,6 +4,8 @@ import { waitForOperationToFinish, setup4337Playground } from '../utils'
 
 dotenv.config({ path: './playground/relay-kit/.env' })
 
+// Load environment variables from ./.env file
+// Follow .env-sample as an example to create your own file
 const {
   PRIVATE_KEY,
   SAFE_ADDRESS = '0x',

playground/relay-kit/userop-verifying-paymaster-counterfactual.ts

@@ -5,6 +5,8 @@ import { privateKeyToAccount } from 'viem/accounts'
 
 dotenv.config({ path: './playground/relay-kit/.env' })
 
+// Load environment variables from ./.env file
+// Follow .env-sample as an example to create your own file
 const {
   PRIVATE_KEY,
   RPC_URL = '',

playground/relay-kit/userop-verifying-paymaster.ts

@@ -4,6 +4,8 @@ import { setup4337Playground, waitForOperationToFinish } from '../utils'
 
 dotenv.config({ path: './playground/relay-kit/.env' })
 
+// Load environment variables from ./.env file
+// Follow .env-sample as an example to create your own file
 const {
   PRIVATE_KEY,
   SAFE_ADDRESS = '0x',

playground/relay-kit/userop.ts

@@ -5,6 +5,8 @@ import { setup4337Playground, waitForOperationToFinish } from '../utils'
 
 dotenv.config({ path: './playground/relay-kit/.env' })
 
+// Load environment variables from ./.env file
+// Follow .env-sample as an example to create your own file
 const {
   PRIVATE_KEY,
   SAFE_ADDRESS = '0x',

playground/sdk-starter-kit/owner-management.ts

@@ -5,6 +5,8 @@ import { privateKeyToAddress } from 'viem/accounts'
 
 dotenv.config({ path: './playground/sdk-starter-kit/.env' })
 
+// Load environment variables from ./.env file
+// Follow .env-sample as an example to create your own file
 const {
   OWNER_1_PRIVATE_KEY = '0x',
   OWNER_2_PRIVATE_KEY = '0x',

playground/sdk-starter-kit/send-off-chain-message.ts

@@ -5,6 +5,8 @@ import { SafeClientResult, createSafeClient, offChainMessages } from '@safe-glob
 
 dotenv.config({ path: './playground/sdk-starter-kit/.env' })
 
+// Load environment variables from ./.env file
+// Follow .env-sample as an example to create your own file
 const {
   OWNER_1_PRIVATE_KEY = '0x',
   OWNER_2_PRIVATE_KEY = '0x',

playground/sdk-starter-kit/send-on-chain-message.ts

@@ -5,6 +5,8 @@ import { SafeClientResult, createSafeClient, onChainMessages } from '@safe-globa
 
 dotenv.config({ path: './playground/sdk-starter-kit/.env' })
 
+// Load environment variables from ./.env file
+// Follow .env-sample as an example to create your own file
 const {
   OWNER_1_PRIVATE_KEY = '0x',
   OWNER_2_PRIVATE_KEY = '0x',