Onchain trackid via paymentReceiver & refundReceiver

packages/protocol-kit/src/Safe.ts

@@ -84,6 +84,7 @@ import { asHash, asHex } from './utils/types'
 import { Hash, Hex } from 'viem'
 import getPasskeyOwnerAddress from './utils/passkeys/getPasskeyOwnerAddress'
 import createPasskeyDeploymentTransaction from './utils/passkeys/createPasskeyDeploymentTransaction'
+import formatTrackId from './utils/on-chain-tracking/formatTrackId'
 
 const EQ_OR_GT_1_4_1 = '>=1.4.1'
 const EQ_OR_GT_1_3_0 = '>=1.3.0'
@@ -100,6 +101,9 @@ class Safe {
   #MAGIC_VALUE = '0x1626ba7e'
   #MAGIC_VALUE_BYTES = '0x20c13b0b'
 
+  // On-chain Analitics
+  #trackId: string = ''
+
   /**
    * Creates an instance of the Safe Core SDK.
    * @param config - Ethers Safe configuration
@@ -124,7 +128,11 @@ class Safe {
    * @throws "MultiSendCallOnly contract is not deployed on the current network"
    */
   async #initializeProtocolKit(config: SafeConfig) {
-    const { provider, signer, isL1SafeSingleton, contractNetworks } = config
+    const { provider, signer, isL1SafeSingleton, contractNetworks, trackId } = config
+
+    if (trackId) {
+      this.#trackId = formatTrackId(trackId)
+    }
 
     this.#safeProvider = await SafeProvider.init({
       provider,
@@ -252,6 +260,7 @@ class Safe {
       safeProvider: this.#safeProvider,
       chainId,
       customContracts: this.#contractManager.contractNetworks?.[chainId.toString()],
+      trackId: this.#trackId,
       ...this.#predictedSafe
     })
   }
@@ -284,6 +293,7 @@ class Safe {
         chainId,
         isL1SafeSingleton: this.#contractManager.isL1SafeSingleton,
         customContracts: this.#contractManager.contractNetworks?.[chainId.toString()],
+        trackId: this.#trackId,
         ...this.#predictedSafe
       })
     }
@@ -534,7 +544,8 @@ class Safe {
           predictedSafe: this.#predictedSafe,
           provider: this.#safeProvider.provider,
           tx: newTransaction,
-          contractNetworks: this.#contractManager.contractNetworks
+          contractNetworks: this.#contractManager.contractNetworks,
+          trackId: this.#trackId
         })
       )
     }
@@ -547,7 +558,8 @@ class Safe {
         safeContract: this.#contractManager.safeContract,
         provider: this.#safeProvider.provider,
         tx: newTransaction,
-        contractNetworks: this.#contractManager.contractNetworks
+        contractNetworks: this.#contractManager.contractNetworks,
+        trackId: this.#trackId
       })
     )
   }
@@ -1545,7 +1557,8 @@ class Safe {
       safeContract: safeSingletonContract,
       safeAccountConfig: safeAccountConfig,
       customContracts,
-      deploymentType
+      deploymentType,
+      trackId: this.#trackId
     })
 
     const safeDeployTransactionData = {
@@ -1698,6 +1711,10 @@ class Safe {
   }): ContractInfo | undefined => {
     return getContractInfo(contractAddress)
   }
+
+  getTrackId(): string {
+    return this.#trackId
+  }
 }
 
 export default Safe

packages/protocol-kit/src/contracts/utils.ts

@@ -75,6 +75,7 @@ export interface PredictSafeAddressProps {
   safeDeploymentConfig?: SafeDeploymentConfig
   isL1SafeSingleton?: boolean
   customContracts?: ContractNetworkConfig
+  trackId?: string
 }
 
 export interface encodeSetupCallDataProps {
@@ -84,6 +85,7 @@ export interface encodeSetupCallDataProps {
   customContracts?: ContractNetworkConfig
   customSafeVersion?: SafeVersion
   deploymentType?: DeploymentType
+  trackId?: string
 }
 
 export function encodeCreateProxyWithNonce(
@@ -109,7 +111,8 @@ export async function encodeSetupCallData({
   safeContract,
   customContracts,
   customSafeVersion,
-  deploymentType
+  deploymentType,
+  trackId
 }: encodeSetupCallDataProps): Promise<string> {
   const {
     owners,
@@ -119,7 +122,7 @@ export async function encodeSetupCallData({
     fallbackHandler,
     paymentToken = ZERO_ADDRESS,
     payment = 0,
-    paymentReceiver = ZERO_ADDRESS
+    paymentReceiver = trackId || ZERO_ADDRESS
   } = safeAccountConfig
 
   const safeVersion = customSafeVersion || safeContract.safeVersion
@@ -255,7 +258,8 @@ export async function getPredictedSafeAddressInitCode({
   safeAccountConfig,
   safeDeploymentConfig = {},
   isL1SafeSingleton,
-  customContracts
+  customContracts,
+  trackId = ''
 }: PredictSafeAddressProps): Promise<string> {
   validateSafeAccountConfig(safeAccountConfig)
   validateSafeDeploymentConfig(safeDeploymentConfig)
@@ -289,7 +293,8 @@ export async function getPredictedSafeAddressInitCode({
     safeContract,
     customContracts,
     customSafeVersion: safeVersion, // it is more efficient if we provide the safeVersion manually
-    deploymentType
+    deploymentType,
+    trackId
   })
 
   const encodedNonce = safeProvider.encodeParameters('uint256', [saltNonce])
@@ -315,7 +320,8 @@ export async function predictSafeAddress({
   safeAccountConfig,
   safeDeploymentConfig = {},
   isL1SafeSingleton,
-  customContracts
+  customContracts,
+  trackId = ''
 }: PredictSafeAddressProps): Promise<string> {
   validateSafeAccountConfig(safeAccountConfig)
   validateSafeDeploymentConfig(safeDeploymentConfig)
@@ -357,7 +363,8 @@ export async function predictSafeAddress({
     safeContract,
     customContracts,
     customSafeVersion: safeVersion, // it is more efficient if we provide the safeVersion manuall
-    deploymentType
+    deploymentType,
+    trackId
   })
   const initializerHash = keccak256(asHex(initializer))
 

packages/protocol-kit/src/index.ts

@@ -67,6 +67,7 @@ import {
 } from './utils/eip-712'
 import { createPasskeyClient } from './utils/passkeys/PasskeyClient'
 import getPasskeyOwnerAddress from './utils/passkeys/getPasskeyOwnerAddress'
+import formatTrackId from './utils/on-chain-tracking/formatTrackId'
 
 export {
   estimateTxBaseGas,
@@ -75,6 +76,7 @@ export {
   estimateSafeDeploymentGas,
   extractPasskeyData,
   extractPasskeyCoordinates,
+  formatTrackId,
   ContractManager,
   CreateCallBaseContract,
   createERC20TokenTransferTransaction,

packages/protocol-kit/src/types/safeConfig.ts

@@ -48,6 +48,8 @@ export type SafeConfigProps = {
   isL1SafeSingleton?: boolean
   /** contractNetworks - Contract network configuration */
   contractNetworks?: ContractNetworksConfig
+  // on-chain analitics
+  trackId?: string
 }
 
 export type SafeConfigWithSafeAddress = SafeConfigProps & SafeConfigWithSafeAddressProps
@@ -75,6 +77,8 @@ type ConnectSafeConfigProps = {
   isL1SafeSingleton?: boolean
   /** contractNetworks - Contract network configuration */
   contractNetworks?: ContractNetworksConfig
+  // on-chain analitics
+  trackId?: string
 }
 
 export type ConnectSafeConfigWithSafeAddress = ConnectSafeConfigProps &

packages/protocol-kit/src/types/transactions.ts

@@ -37,6 +37,7 @@ type StandardizeSafeTransactionData = {
   tx: SafeTransactionDataPartial
   /** contractNetworks - Contract network configuration */
   contractNetworks?: ContractNetworksConfig
+  trackId: string
 }
 
 export type StandardizeSafeTxDataWithSafeContract = StandardizeSafeTransactionData &

packages/protocol-kit/src/utils/on-chain-tracking/formatTrackId.ts

@@ -0,0 +1,14 @@
+import { keccak256, toHex } from 'viem'
+
+/**
+ * Formats a trackId to convert it into an Ethereum address. This address can be used in
+ * fields like `paymentReceiver` and `refundReceiver` to track Safe transactions and deployments.
+ *
+ * @param {string} trackId - The identifier provided by the user.
+ * @returns {`0x${string}`} - The Ethereum address derived from the identifier.
+ */
+function formatTrackId(trackId: string): `0x${string}` {
+  return `0x${keccak256(toHex(trackId)).substring(2, 42)}` // only first 40 chars from the hash
+}
+
+export default formatTrackId

packages/protocol-kit/src/utils/transactions/utils.ts

@@ -61,7 +61,8 @@ export async function standardizeSafeTransactionData({
   predictedSafe,
   provider,
   tx,
-  contractNetworks
+  contractNetworks,
+  trackId
 }: StandardizeSafeTransactionDataProps): Promise<SafeTransactionData> {
   const standardizedTxs = {
     to: tx.to,
@@ -71,7 +72,7 @@ export async function standardizeSafeTransactionData({
     baseGas: tx.baseGas ?? '0',
     gasPrice: tx.gasPrice ?? '0',
     gasToken: tx.gasToken || ZERO_ADDRESS,
-    refundReceiver: tx.refundReceiver || ZERO_ADDRESS,
+    refundReceiver: tx.refundReceiver || trackId || ZERO_ADDRESS,
     nonce: tx.nonce ?? (safeContract ? Number(await safeContract.getNonce()) : 0)
   }