Message signatures
Using the Protocol Kit, this guide explains how to generate and sign messages from a Safe account, including plain string messages and EIP-712 JSON messages.
Before starting, check this guide's setup.
Prerequisites
Steps
Install dependencies
_10yarn install @safe-global/protocol-kit
Create a message
Messages can be plain strings or valid EIP-712 typed data structures.
_10// An example of a string message_10const STRING_MESSAGE = "I'm the owner of this Safe account"
_47// An example of a typed data message_47const TYPED_MESSAGE = {_47 types: {_47 EIP712Domain: [_47 { name: 'name', type: 'string' },_47 { name: 'version', type: 'string' },_47 { name: 'chainId', type: 'uint256' },_47 { name: 'verifyingContract', type: 'address' }_47 ],_47 Person: [_47 { name: 'name', type: 'string' },_47 { name: 'wallets', type: 'address[]' }_47 ],_47 Mail: [_47 { name: 'from', type: 'Person' },_47 { name: 'to', type: 'Person[]' },_47 { name: 'contents', type: 'string' }_47 ]_47 },_47 domain: {_47 name: 'Ether Mail',_47 version: '1',_47 chainId: Number(chainId),_47 verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC'_47 },_47 primaryType: 'Mail',_47 message: {_47 from: {_47 name: 'Cow',_47 wallets: [_47 '0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826',_47 '0xDeaDbeefdEAdbeefdEadbEEFdeadbeEFdEaDbeeF'_47 ]_47 },_47 to: [_47 {_47 name: 'Bob',_47 wallets: [_47 '0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB',_47 '0xB0BdaBea57B0BDABeA57b0bdABEA57b0BDabEa57',_47 '0xB0B0b0b0b0b0B000000000000000000000000000'_47 ]_47 }_47 ],_47 contents: 'Hello, Bob!'_47 }_47}
The createMessage method in the Protocol Kit allows for creating new messages and returns an instance of the EthSafeMessage class. Here, we are passing TYPED_MESSAGE, but STRING_MESSAGE could also be passed.
_10let safeMessage = protocolKit.createMessage(TYPED_MESSAGE)
The returned safeMessage object contains the message data (safeMessage.data) and a map of owner-signature pairs (safeMessage.signatures). The structure is similar to the EthSafeTransaction class but applied for messages instead of transactions.
We use let to initialize the safeMessage variable because we will add the signatures later.
_10class EthSafeMessage implements SafeMessage {_10 data: EIP712TypedData | string_10 signatures: Map<string, SafeSignature> = new Map()_10 ..._10 // Other props and methods_10}
Sign the message
Once the safeMessage object is created, we need to collect the signatures from the signers who will sign it.
Following our setup, we will sign a message with safe3_4, the main Safe account in this guide. To do that, we first need to sign the same message with its owners: owner1, owner2, safe1_1, and safe2_3.
ECDSA signatures
This applies to owner1 and owner2 accounts, as both are EOAs.
The signMessage method takes the safeMessage together with a SigningMethod and adds the new signature to the signMessage.signatures map. Depending on the type of message, the SigningMethod can take these values:
SigningMethod.ETH_SIGNSigningMethod.ETH_SIGN_TYPED_DATA_V4
_19// Connect the EthAdapter from owner1_19protocolKit = await protocolKit.connect({ ethAdapter: ethAdapter1 })_19_19// Sign the safeMessage with owner1_19// After this, the safeMessage contains the signature from owner1_19safeMessage = await protocolKit.signMessage(_19 safeMessage,_19 SigningMethod.ETH_SIGN_TYPED_DATA_V4_19)_19_19// Connect the EthAdapter from owner2_19protocolKit = await protocolKit.connect({ ethAdapter: ethAdapter2 })_19_19// Sign the safeMessage with owner2_19// After this, the safeMessage contains the signature from owner1 and owner2_19safeMessage = await protocolKit.signMessage(_19 safeMessage,_19 SigningMethod.ETH_SIGN_TYPED_DATA_V4_19)
Smart contract signatures
When signing with a Safe account, the SigningMethod will take the value SigningMethod.SAFE_SIGNATURE.
1/1 Safe account
This applies to the safe1_1 account, another owner of safe3_4.
We need to connect the Protocol Kit to safe1_1 and the owner3 account (the only owner of safe1_1) and sign the message.
_26// Create a new message object_26let messageSafe1_1 = await createMessage(TYPED_MESSAGE)_26_26// Connect the EthAdapter from owner3 and the address of safe1_1_26protocolKit = await protocolKit.connect({_26 ethAdapter: ethAdapter3,_26 safeAddress: safe1_1_26})_26_26// Sign the messageSafe1_1 with owner3_26// After this, the messageSafe1_1 contains the signature from owner3_26messageSafe1_1 = await signMessage(_26 messageSafe1_1,_26 SigningMethod.SAFE_SIGNATURE,_26 safe3_4 // Parent Safe address_26)_26_26// Build the contract signature of safe1_1_26const signatureSafe1_1 = await buildContractSignature(_26 Array.from(messageSafe1_1.signatures.values()),_26 safe1_1_26)_26_26// Add the signatureSafe1_1 to safeMessage_26// After this, the safeMessage contains the signature from owner1, owner2 and safe1_1_26safeMessage.addSignature(signatureSafe1_1)
When signing with a child Safe account, we need to specify the parent Safe address to generate the signature based on the version of the contract.
2/3 Safe account
This applies to the safe2_3 account, another owner of safe3_4.
We need to connect the Protocol Kit to safe2_3 and the owner4 and owner5 accounts (owners of safe2_3) and sign the message.
_37// Create a new message object_37let messageSafe2_3 = await createMessage(TYPED_MESSAGE)_37_37// Connect the EthAdapter from owner4 and the address of safe2_3_37protocolKit = await protocolKit.connect({_37 ethAdapter: ethAdapter4,_37 safeAddress: safe2_3_37})_37_37// Sign the messageSafe2_3 with owner4_37// After this, the messageSafe2_3 contains the signature from owner4_37messageSafe2_3 = await protocolKit.signMessage(_37 messageSafe2_3,_37 SigningMethod.SAFE_SIGNATURE,_37 safe3_4 // Parent Safe address_37)_37_37// Connect the EthAdapter from owner5_37protocolKit = await protocolKit.connect({ ethAdapter: ethAdapter5 })_37_37// Sign the messageSafe2_3 with owner5_37// After this, the messageSafe2_3 contains the signature from owner5_37messageSafe2_3 = await protocolKit.signMessage(_37 messageSafe2_3,_37 SigningMethod.SAFE_SIGNATURE,_37 safe3_4 // Parent Safe address_37)_37_37// Build the contract signature of safe2_3_37const signatureSafe2_3 = await buildContractSignature(_37 Array.from(messageSafe2_3.signatures.values()),_37 safe2_3_37)_37_37// Add the signatureSafe2_3 to safeMessage_37// After this, the safeMessage contains the signature from owner1, owner2, safe1_1 and safe2_3_37safeMessage.addSignature(signatureSafe2_3)
After following all the steps above, the safeMessage now contains all the signatures from the owners of the Safe.
Publish the signed message
As messages aren't stored in the blockchain, we must make them public and available to others by storing them elsewhere.
Safe messages can be stored on-chain and off-chain:
- Off-chain: Messages are stored in the Safe Transaction Service. This is the default option and doesn't require any on-chain interaction.
- On-chain: Messages are stored (opens in a new tab) in the Safe contract.
Safe supports signing EIP-191 (opens in a new tab) messages and EIP-712 (opens in a new tab) typed data messages all together with off-chain EIP-1271 (opens in a new tab) validation for signatures.
Off-chain messages
To use off-chain messages, we need to use the functionality from this guide and call the Safe Transaction Service API to store the messages and signatures.
We mentioned the utility of storing messages in the contract. Off-chain messages have the same purpose, but they're stored in the Safe Transaction Service. It stores the messages and signatures in a database. It's a centralized service, but it's open-source and can be deployed by anyone.
The Safe Transaction Service is used by Safe{Wallet} to store messages and signatures by default.
Propose the message
To store a new message, we need to call the addMessage from the API Kit, passing the Safe address, an object with the message, and a signature from one owner.
_14const signerAddress = (await ethAdapter1.getSignerAddress()) || '0x'_14_14// Get the signature from owner1_14const signatureOwner1 = safeMessage.getSignature(signerAddress) as EthSafeSignature_14_14// Instantiate the API Kit_14// Use the chainId where you have the Safe account deployed_14const apiKit = new SafeApiKit({ chainId })_14_14// Propose the message_14apiKit.addMessage(safe3_4, {_14 message: TYPED_MESSAGE, // or STRING_MESSAGE_14 signature: buildSignatureBytes([signatureOwner1])_14})
The message is now publicly available in the Safe Transaction Service with the signature of the owner who submitted it.
Confirm the message
To add the signatures from the remaining owners, we need to call the addMessageSignature, passing the safeMessageHash and a signature from the owner.
_26// Get the safeMessageHash_26const safeMessageHash = await protocolKit.getSafeMessageHash(_26 hashSafeMessage(TYPED_MESSAGE) // or STRING_MESSAGE_26)_26_26// Get the signature from owner2_26const signerAddress = (await ethAdapter2.getSignerAddress()) || '0x'_26const signatureOwner2 = safeMessage.getSignature(signerAddress) as EthSafeSignature_26_26// Add signature from owner2_26await apiKit.addMessageSignature(_26 safeMessageHash,_26 buildSignatureBytes([signatureOwner2])_26)_26_26// Add signature from the owner safe1_1_26await apiKit.addMessageSignature(_26 safeMessageHash,_26 buildSignatureBytes([signatureSafe1_1])_26)_26_26// Add signature from the owner safe2_3_26await apiKit.addMessageSignature(_26 safeMessageHash,_26 buildSignatureBytes([signatureSafe2_3])_26)
At this point, the message stored in the Safe Transaction Service contains all the required signatures from the owners of the Safe.
The getMessage method returns the status of a message.
_10const confirmedMessage = await apiKit.getMessage(safeMessageHash)
Safe{Wallet} (opens in a new tab) exposes to its users the list of off-chain messages signed by a Safe account.
_10https://app.safe.global/transactions/messages?safe=<NETWORK_PREFIX>:<SAFE_ADDRESS>
On-chain messages
Storing messages on-chain is less efficient than doing it off-chain because it requires executing a transaction to store the message hash in the contract, resulting in additional gas costs. To do this on-chain, we use the SignMessageLib contract.
_10// Get the contract with the correct version_10const signMessageLibContract = await ethAdapter1.getSignMessageLibContract({_10 safeVersion: '1.4.1'_10})
We need to calculate the messageHash, encode the call to the signMessage function in the SignMessageLib contract and create the transaction that will store the message hash in that contract.
_13const messageHash = hashSafeMessage(MESSAGE)_13const txData = signMessageLibContract.encode('signMessage', [messageHash])_13_13const safeTransactionData: SafeTransactionDataPartial = {_13 to: signMessageLibContract.address,_13 value: '0',_13 data: txData,_13 operation: OperationType.DelegateCall,_13}_13_13const signMessageTx = await protocolKit.createTransaction({_13 transactions: [safeTransactionData]_13})
Once the transaction object is instantiated, the owners must sign and execute it.
_10// Collect the signatures using the signTransaction method_10_10// Execute the transaction to store the messageHash_10await protocolKit.executeTransaction(signMessageTx)
Once the transaction is executed, the message hash will be stored in the contract.
Validate the signature
On-chain
When a message is stored on-chain, the isValidSignature method in the Protocol Kit needs to be called with the parameters messageHash and 0x. The method will check the stored hashes in the Safe contract to validate the signature.
_10import { hashSafeMessage } from '@safe-global/protocol-kit'_10_10const messageHash = hashSafeMessage(MESSAGE)_10_10const isValid = await protocolKit.isValidSignature(messageHash, '0x')
Off-chain
When a message is stored off-chain, the isValidSignature method in the Protocol Kit must be called with the messageHash and the encodedSignatures parameters. The method will check the isValidSignature function defined in the CompatibilityFallbackHandler contract (opens in a new tab) to validate the signature.
_10const encodedSignatures = safeMessage.encodedSignatures()_10_10const isValid = await protocolKit.isValidSignature(_10 messageHash,_10 encodedSignatures_10)