Protocol Kit

The Protocol Kit facilitates the interaction with the Safe contracts.

Install dependencies

To add the Protocol Kit to your project, run:

yarn add @safe-global/protocol-kit

Safe Factory reference

`create`

Returns an instance of the Safe Factory.

import { SafeFactory } from '@safe-global/protocol-kit'

const safeFactory = await SafeFactory.create({ ethAdapter })

The isL1SafeMasterCopy flag

There are two versions of the Safe contracts: Safe.sol that does not trigger events in order to save gas and SafeL2.sol that does, which is more appropriate for L2 networks.

By default Safe.sol will be only used on Ethereum Mainnet. For the rest of the networks where the Safe contracts are already deployed, the SafeL2.sol contract will be used unless you add the isL1SafeMasterCopy flag to force the use of the Safe.sol contract.
```
const safeFactory = await SafeFactory.create({ ethAdapter, isL1SafeMasterCopy: true })
```

The contractNetworks property

If the Safe contracts are not deployed to your current network, the contractNetworks property will be required to point to the addresses of the Safe contracts previously deployed by you.

import { ContractNetworksConfig } from '@safe-global/protocol-kit'

const chainId = await ethAdapter.getChainId()
const contractNetworks: ContractNetworksConfig = {
  [chainId]: {
    safeMasterCopyAddress: '<MASTER_COPY_ADDRESS>',
    safeProxyFactoryAddress: '<PROXY_FACTORY_ADDRESS>',
    multiSendAddress: '<MULTI_SEND_ADDRESS>',
    multiSendCallOnlyAddress: '<MULTI_SEND_CALL_ONLY_ADDRESS>',
    fallbackHandlerAddress: '<FALLBACK_HANDLER_ADDRESS>',
    signMessageLibAddress: '<SIGN_MESSAGE_LIB_ADDRESS>',
    createCallAddress: '<CREATE_CALL_ADDRESS>',
    simulateTxAccessorAddress: '<SIMULATE_TX_ACCESSOR_ADDRESS>',
    safeMasterCopyAbi: '<MASTER_COPY_ABI>', // Optional. Only needed with web3.js
    safeProxyFactoryAbi: '<PROXY_FACTORY_ABI>', // Optional. Only needed with web3.js
    multiSendAbi: '<MULTI_SEND_ABI>', // Optional. Only needed with web3.js
    multiSendCallOnlyAbi: '<MULTI_SEND_CALL_ONLY_ABI>', // Optional. Only needed with web3.js
    fallbackHandlerAbi: '<FALLBACK_HANDLER_ABI>', // Optional. Only needed with web3.js
    signMessageLibAbi: '<SIGN_MESSAGE_LIB_ABI>', // Optional. Only needed with web3.js
    createCallAbi: '<CREATE_CALL_ABI>', // Optional. Only needed with web3.js
    simulateTxAccessorAbi: '<SIMULATE_TX_ACCESSOR_ABI>' // Optional. Only needed with web3.js
  }
}

const safeFactory = await SafeFactory.create({ ethAdapter, contractNetworks })

The safeVersion property

The SafeFactory constructor also accepts the safeVersion property to specify the Safe contract version that will be deployed. This string can take the values 1.0.0, 1.1.1, 1.2.0, 1.3.0 or 1.4.1. If not specified, the DEFAULT_SAFE_VERSION value will be used.
```
const safeVersion = 'X.Y.Z'
const safeFactory = await SafeFactory.create({ ethAdapter, safeVersion })
```

`deploySafe`

Deploys a new Safe and returns an instance of the Protocol Kit connected to the deployed Safe. The address of the Master Copy, Safe contract version and the contract (Safe.sol or SafeL2.sol) of the deployed Safe will depend on the initialization of the safeFactory instance.

const safeAccountConfig: SafeAccountConfig = {
  owners,
  threshold,
  to, // Optional
  data, // Optional
  fallbackHandler, // Optional
  paymentToken, // Optional
  payment, // Optional
  paymentReceiver // Optional
}

const safeSdk = await safeFactory.deploySafe({ safeAccountConfig })

This method can optionally receive the saltNonce parameter.

const safeAccountConfig: SafeAccountConfig = {
  owners,
  threshold,
  to, // Optional
  data, // Optional
  fallbackHandler, // Optional
  paymentToken, // Optional
  payment, // Optional
  paymentReceiver // Optional
}

const saltNonce = '<YOUR_CUSTOM_VALUE>'

const safeSdk = await safeFactory.deploySafe({ safeAccountConfig, saltNonce })

Optionally, some properties can be passed as execution options:

const options: Web3TransactionOptions = {
  from, // Optional
  gas, // Optional
  gasPrice, // Optional
  maxFeePerGas, // Optional
  maxPriorityFeePerGas // Optional
  nonce // Optional
}

const options: EthersTransactionOptions = {
  from, // Optional
  gasLimit, // Optional
  gasPrice, // Optional
  maxFeePerGas, // Optional
  maxPriorityFeePerGas // Optional
  nonce // Optional
}

const safeSdk = await safeFactory.deploySafe({ safeAccountConfig, safeDeploymentConfig, options })

It can also take an optional callback which receives the txHash of the Safe deployment transaction prior to returning a new instance of the Protocol Kit:

const callback = (txHash: string): void => {
  console.log({ txHash })
}

const safeSdk = await safeFactory.deploySafe({ safeAccountConfig, callback })

Safe reference

`create`

Returns an instance of the Protocol Kit connected to a Safe. The provided Safe must be a safeAddress or a predictedSafe.

Initialization of a deployed Safe using the safeAddress property:

import Safe from '@safe-global/protocol-kit'

const safeSdk = await Safe.create({ ethAdapter, safeAddress })

Initialization of a not deployed Safe using the predictedSafe property. Because Safes are deployed in a deterministic way, passing a predictedSafe will allow to initialize the SDK with the Safe configuration and use it to some extent before it is deployed:

import Safe, { PredictedSafeProps } from '@safe-global/protocol-kit'

const predictedSafe: PredictedSafeProps = {
  safeAccountConfig,
  safeDeploymentConfig
}

const safeSdk = await Safe.create({ ethAdapter, predictedSafe })

The isL1SafeMasterCopy flag

There are two versions of the Safe contracts: Safe.sol that does not trigger events in order to save gas and SafeL2.sol that does, which is more appropriate for L2 networks.

By default Safe.sol will be only used on Ethereum Mainnet. For the rest of the networks where the Safe contracts are already deployed, the SafeL2.sol contract will be used unless you add the isL1SafeMasterCopy flag to force the use of the Safe.sol contract.
```
const safeSdk = await Safe.create({ ethAdapter, safeAddress, isL1SafeMasterCopy: true })
```

The contractNetworks property

If the Safe contracts are not deployed to your current network, the contractNetworks property will be required to point to the addresses of the Safe contracts previously deployed by you.

import { ContractNetworksConfig } from '@safe-global/protocol-kit'

const chainId = await ethAdapter.getChainId()
const contractNetworks: ContractNetworksConfig = {
  [chainId]: {
    safeMasterCopyAddress: '<MASTER_COPY_ADDRESS>',
    safeProxyFactoryAddress: '<PROXY_FACTORY_ADDRESS>',
    multiSendAddress: '<MULTI_SEND_ADDRESS>',
    multiSendCallOnlyAddress: '<MULTI_SEND_CALL_ONLY_ADDRESS>',
    fallbackHandlerAddress: '<FALLBACK_HANDLER_ADDRESS>',
    signMessageLibAddress: '<SIGN_MESSAGE_LIB_ADDRESS>',
    createCallAddress: '<CREATE_CALL_ADDRESS>',
    simulateTxAccessorAddress: '<SIMULATE_TX_ACCESSOR_ADDRESS>',
    safeMasterCopyAbi: '<MASTER_COPY_ABI>', // Optional. Only needed with web3.js
    safeProxyFactoryAbi: '<PROXY_FACTORY_ABI>', // Optional. Only needed with web3.js
    multiSendAbi: '<MULTI_SEND_ABI>', // Optional. Only needed with web3.js
    multiSendCallOnlyAbi: '<MULTI_SEND_CALL_ONLY_ABI>', // Optional. Only needed with web3.js
    fallbackHandlerAbi: '<FALLBACK_HANDLER_ABI>', // Optional. Only needed with web3.js
    signMessageLibAbi: '<SIGN_MESSAGE_LIB_ABI>', // Optional. Only needed with web3.js
    createCallAbi: '<CREATE_CALL_ABI>', // Optional. Only needed with web3.js
    simulateTxAccessorAbi: '<SIMULATE_TX_ACCESSOR_ABI>' // Optional. Only needed with web3.js
  }
}

const safeSdk = await Safe.create({ ethAdapter, safeAddress, contractNetworks })

`connect`

Returns a new instance of the Protocol Kit connected to a new Safe or a new Signer. The new connected signer can be passed via the ethAdapter property while the new connected Safe can be passed using a safeAddress or a predictedSafe.

Connection of a deployed Safe using the safeAddress property:

const safeSdk = await safeSdk.connect({ ethAdapter, safeAddress })

Connection of a not deployed Safe using the predictedSafe property. Because Safes are deployed in a deterministic way, passing a predictedSafe will allow to connect a Safe to the SDK with the Safe configuration:

import { PredictedSafeProps } from '@safe-global/protocol-kit'

const predictedSafe: PredictedSafeProps = {
  safeAccountConfig,
  safeDeploymentConfig
}

const safeSdk = await safeSdk.connect({ ethAdapter, predictedSafe })

The isL1SafeMasterCopy flag

There are two versions of the Safe contracts: Safe.sol that does not trigger events in order to save gas and SafeL2.sol that does, which is more appropriate for L2 networks.

By default Safe.sol will be only used on Ethereum Mainnet. For the rest of the networks where the Safe contracts are already deployed, the SafeL2.sol contract will be used unless you add the isL1SafeMasterCopy flag to force the use of the Safe.sol contract.
```
const safeSdk = await Safe.connect({ ethAdapter, safeAddress, isL1SafeMasterCopy: true })
```

The contractNetworks property

If the Safe contracts are not deployed to your current network, the contractNetworks property will be required to point to the addresses of the Safe contracts previously deployed by you.

import { ContractNetworksConfig } from '@safe-global/protocol-kit'

const chainId = await ethAdapter.getChainId()
const contractNetworks: ContractNetworksConfig = {
  [chainId]: {
    safeMasterCopyAddress: '<MASTER_COPY_ADDRESS>',
    safeProxyFactoryAddress: '<PROXY_FACTORY_ADDRESS>',
    multiSendAddress: '<MULTI_SEND_ADDRESS>',
    multiSendCallOnlyAddress: '<MULTI_SEND_CALL_ONLY_ADDRESS>',
    fallbackHandlerAddress: '<FALLBACK_HANDLER_ADDRESS>',
    signMessageLibAddress: '<SIGN_MESSAGE_LIB_ADDRESS>',
    createCallAddress: '<CREATE_CALL_ADDRESS>',
    simulateTxAccessorAddress: '<SIMULATE_TX_ACCESSOR_ADDRESS>',
    safeMasterCopyAbi: '<MASTER_COPY_ABI>', // Optional. Only needed with web3.js
    safeProxyFactoryAbi: '<PROXY_FACTORY_ABI>', // Optional. Only needed with web3.js
    multiSendAbi: '<MULTI_SEND_ABI>', // Optional. Only needed with web3.js
    multiSendCallOnlyAbi: '<MULTI_SEND_CALL_ONLY_ABI>', // Optional. Only needed with web3.js
    fallbackHandlerAbi: '<FALLBACK_HANDLER_ABI>', // Optional. Only needed with web3.js
    signMessageLibAbi: '<SIGN_MESSAGE_LIB_ABI>', // Optional. Only needed with web3.js
    createCallAbi: '<CREATE_CALL_ABI>', // Optional. Only needed with web3.js
    simulateTxAccessorAbi: '<SIMULATE_TX_ACCESSOR_ABI>' // Optional. Only needed with web3.js
  }
}
const safeSdk = await Safe.connect({ ethAdapter, safeAddress, contractNetworks })

`getAddress`

Returns the address of the current SafeProxy contract.

const safeAddress = await safeSdk.getAddress()

`getContractVersion`

Returns the Safe Master Copy contract version.

const contractVersion = await safeSdk.getContractVersion()

`getOwners`

Returns the list of Safe owner accounts.

const ownerAddresses = await safeSdk.getOwners()

`getNonce`

Returns the Safe nonce.

const nonce = await safeSdk.getNonce()

`getThreshold`

Returns the Safe threshold.

const threshold = await safeSdk.getThreshold()

`getChainId`

Returns the chainId of the connected network.

const chainId = await safeSdk.getChainId()

`getBalance`

Returns the ETH balance of the Safe.

const balance = await safeSdk.getBalance()

`getGuard`

Returns the enabled Safe Guard or 0x address if no guards are enabled.

const guardAddress = await safeSdk.getGuard()

`getModules`

Returns the list of addresses of all the enabled Safe Modules.

const moduleAddresses = await safeSdk.getModules()

`isModuleEnabled`

Checks if a specific Safe Module is enabled for the current Safe.

const isEnabled = await safeSdk.isModuleEnabled(moduleAddress)

`isOwner`

Checks if a specific address is an owner of the current Safe.

const isOwner = await safeSdk.isOwner(address)

`createTransaction`

Returns a Safe transaction ready to be signed by the owners and executed. The Protocol Kit supports the creation of single Safe transactions but also MultiSend transactions.

Single transactions

This method can take an object of type SafeTransactionDataPartial that represents the transaction we want to execute (once the signatures are collected). It accepts some optional properties as follows.

import { SafeTransactionDataPartial } from '@safe-global/safe-core-sdk-types'

const safeTransactionData: SafeTransactionDataPartial = {
  to,
  data,
  value,
  operation, // Optional
  safeTxGas, // Optional
  baseGas, // Optional
  gasPrice, // Optional
  gasToken, // Optional
  refundReceiver, // Optional
  nonce // Optional
}
const safeTransaction = await safeSdk.createTransaction({ safeTransactionData })

MultiSend transactions

This method can take an array of MetaTransactionData objects that represent the multiple transactions we want to include in our MultiSend transaction. If we want to specify some of the optional properties in our MultiSend transaction, we can pass a second argument to the createTransaction method with the SafeTransactionOptionalProps object.

const safeTransactionData: MetaTransactionData[] = [
  {
    to,
    data,
    value,
    operation // Optional
  },
  {
    to,
    data,
    value,
    operation // Optional
  }
  // ...
]
const safeTransaction = await safeSdk.createTransaction({ safeTransactionData })

This method can also receive the options parameter to set the optional properties in the MultiSend transaction:

const safeTransactionData: MetaTransactionData[] = [
  {
    to,
    data,
    value,
    operation // Optional
  },
  {
    to,
    data,
    value,
    operation // Optional
  }
  // ...
]
const options: SafeTransactionOptionalProps = {
  safeTxGas, // Optional
  baseGas, // Optional
  gasPrice, // Optional
  gasToken, // Optional
  refundReceiver, // Optional
  nonce // Optional
}
const safeTransaction = await safeSdk.createTransaction({ safeTransactionData, options })

In addition, the optional callsOnly parameter, which is false by default, allows to force the use of the MultiSendCallOnly instead of the MultiSend contract when sending a batch transaction:

const callsOnly = true
const safeTransaction = await safeSdk.createTransaction({
  safeTransactionData,
  options,
  callsOnly
})

If the optional properties are not manually set, the Safe transaction returned will have the default value for each one:

operation: OperationType.Call (0) is the default value.
safeTxGas: The right gas estimation is the default value.
baseGas: 0 is the default value.
gasPrice: 0 is the default value.
gasToken: 0x address is the default value.
refundReceiver: 0x address is the default value.
nonce: The current Safe nonce is the default value.

`createRejectionTransaction`

Returns a Safe transaction ready to be signed by the owners that invalidates the pending Safe transaction/s with a specific nonce.

const safeTransactionData: SafeTransactionDataPartial = {
  // ...
}
const safeTransaction = await safeSdk.createTransaction({ safeTransactionData })
const rejectionTransaction = await safeSdk.createRejectionTransaction(safeTransaction.data.nonce)

`copyTransaction`

Copies a Safe transaction.

const safeTransaction1 = await safeSdk.createTransaction({ safeTransactionData })
const safeTransaction2 = await copyTransaction(safeTransaction1)

`getTransactionHash`

Returns the transaction hash of a Safe transaction.

const safeTransactionData: SafeTransactionDataPartial = {
  // ...
}
const safeTransaction = await safeSdk.createTransaction({ safeTransactionData })
const txHash = await safeSdk.getTransactionHash(safeTransaction)

`signTransactionHash`

Signs a hash using the current owner account.

const safeTransactionData: SafeTransactionDataPartial = {
  // ...
}
const safeTransaction = await safeSdk.createTransaction({ safeTransactionData })
const txHash = await safeSdk.getTransactionHash(safeTransaction)
const signature = await safeSdk.signTransactionHash(txHash)

`signTypedData`

Signs a transaction according to the EIP-712 using the current signer account.

const safeTransactionData: SafeTransactionDataPartial = {
  // ...
}
const safeTransaction = await safeSdk.createTransaction({ safeTransactionData })
const signature = await safeSdk.signTypedData(safeTransaction)

`signTransaction`

Returns a new SafeTransaction object that includes the signature of the current owner. eth_sign will be used by default to generate the signature.

const safeTransactionData: SafeTransactionDataPartial = {
  // ...
}
const safeTransaction = await safeSdk.createTransaction({ safeTransactionData })
const signedSafeTransaction = await safeSdk.signTransaction(safeTransaction)

Optionally, an additional parameter can be passed to specify a different way of signing:

const signedSafeTransaction = await safeSdk.signTransaction(safeTransaction, 'eth_signTypedData')

const signedSafeTransaction = await safeSdk.signTransaction(safeTransaction, 'eth_sign') // default option.

`approveTransactionHash`

Approves a hash on-chain using the current owner account.

const safeTransactionData: SafeTransactionDataPartial = {
  // ...
}
const safeTransaction = await safeSdk.createTransaction({ safeTransactionData })
const txHash = await safeSdk.getTransactionHash(safeTransaction)
const txResponse = await safeSdk.approveTransactionHash(txHash)
await txResponse.transactionResponse?.wait()

Optionally, some properties can be passed as execution options:

const options: Web3TransactionOptions = {
  from, // Optional
  gas, // Optional
  gasPrice, // Optional
  maxFeePerGas, // Optional
  maxPriorityFeePerGas // Optional
  nonce // Optional
}

const options: EthersTransactionOptions = {
  from, // Optional
  gasLimit, // Optional
  gasPrice, // Optional
  maxFeePerGas, // Optional
  maxPriorityFeePerGas // Optional
  nonce // Optional
}

const txResponse = await safeSdk.approveTransactionHash(txHash, options)

`getOwnersWhoApprovedTx`

Returns a list of owners who have approved a specific Safe transaction.

const safeTransactionData: SafeTransactionDataPartial = {
  // ...
}
const safeTransaction = await safeSdk.createTransaction({ safeTransactionData })
const txHash = await safeSdk.getTransactionHash(safeTransaction)
const ownerAddresses = await safeSdk.getOwnersWhoApprovedTx(txHash)