Wallet Integration

The WalletDelegate protocol is the bridge between the Privacy Boost SDK and your wallet. This guide covers implementing it for various wallet types, expanding on the brief examples in Authentication.

Protocol Definition

public protocol WalletDelegate: AnyObject {
    /// Get the connected wallet address
    func getAddress() async throws -> String

    /// Get the current chain ID
    func getChainId() async throws -> UInt64

    /// Sign a personal message (EIP-191)
    func signMessage(message: String) async throws -> String

    /// Sign EIP-712 typed data
    func signTypedData(typedDataJson: String) async throws -> String

    /// Send a transaction
    func sendTransaction(toAddress: String, value: String, data: String) async throws -> String

    /// Wait until a transaction is mined and return its receipt
    func waitForTransactionReceipt(txHash: String) async throws -> TransactionReceipt
}

Implementation Requirements

Return Values

Addresses: Checksummed hex strings with 0x prefix (42 characters)
Signatures: Hex strings with 0x prefix (132 characters for 65 bytes)
Transaction hashes: Hex strings with 0x prefix (66 characters)
Transaction receipts: Mined receipt status and logs from eth_getTransactionReceipt
Chain ID: Integer matching expected network

Async Behavior

All WalletDelegate methods are async throws. The SDK awaits each call, so your implementation can use native Swift concurrency (async/await). The SDK calls waitForTransactionReceipt after sendTransaction to confirm on-chain inclusion and read emitted events.

WalletConnect Integration

Example using WalletConnect Swift SDK:

import WalletConnectSwift

class WalletConnectDelegate: WalletDelegate {
    private let session: Session
    private let client: Client

    init(session: Session, client: Client) {
        self.session = session
        self.client = client
    }

    func getAddress() async throws -> String {
        guard let account = session.walletInfo?.accounts.first else {
            throw WalletError.notConnected
        }
        return account
    }

    func getChainId() async throws -> UInt64 {
        guard let chainId = session.walletInfo?.chainId else {
            throw WalletError.notConnected
        }
        return UInt64(chainId)
    }

    func signMessage(message: String) async throws -> String {
        let semaphore = DispatchSemaphore(value: 0)
        var result: Result<String, Error>?

        let address = try await getAddress()

        try client.personal_sign(
            url: session.url,
            message: message,
            account: address
        ) { response in
            switch response {
            case .success(let signature):
                result = .success(signature)
            case .failure(let error):
                result = .failure(error)
            }
            semaphore.signal()
        }

        semaphore.wait()

        switch result {
        case .success(let signature):
            return signature
        case .failure(let error):
            throw error
        case .none:
            throw WalletError.timeout
        }
    }

    func signTypedData(typedDataJson: String) async throws -> String {
        let semaphore = DispatchSemaphore(value: 0)
        var result: Result<String, Error>?

        let address = try await getAddress()

        try client.eth_signTypedData(
            url: session.url,
            account: address,
            message: typedDataJson
        ) { response in
            switch response {
            case .success(let signature):
                result = .success(signature)
            case .failure(let error):
                result = .failure(error)
            }
            semaphore.signal()
        }

        semaphore.wait()

        switch result {
        case .success(let signature):
            return signature
        case .failure(let error):
            throw error
        case .none:
            throw WalletError.timeout
        }
    }

    func sendTransaction(toAddress: String, value: String, data: String) async throws -> String {
        let semaphore = DispatchSemaphore(value: 0)
        var result: Result<String, Error>?

        let address = try await getAddress()

        let transaction = Client.Transaction(
            from: address,
            to: toAddress,
            data: data,
            gas: nil,
            gasPrice: nil,
            value: value,
            nonce: nil
        )

        try client.eth_sendTransaction(
            url: session.url,
            transaction: transaction
        ) { response in
            switch response {
            case .success(let txHash):
                result = .success(txHash)
            case .failure(let error):
                result = .failure(error)
            }
            semaphore.signal()
        }

        semaphore.wait()

        switch result {
        case .success(let txHash):
            return txHash
        case .failure(let error):
            throw error
        case .none:
            throw WalletError.timeout
        }
    }

    func waitForTransactionReceipt(txHash: String) async throws -> TransactionReceipt {
        // Poll eth_getTransactionReceipt via your RPC client until it returns a receipt.
        return try await pollReceipt(txHash: txHash)
    }
}

enum WalletError: Error {
    case notConnected
    case timeout
    case userRejected
}

Web3.swift Integration

Example using web3.swift with a local keystore:

import web3swift

class Web3Delegate: WalletDelegate {
    private let web3: web3
    private let keystoreManager: KeystoreManager
    private let address: EthereumAddress

    init(web3: web3, keystoreManager: KeystoreManager, address: EthereumAddress) {
        self.web3 = web3
        self.keystoreManager = keystoreManager
        self.address = address
    }

    func getAddress() async throws -> String {
        return address.address
    }

    func getChainId() async throws -> UInt64 {
        guard let chainId = web3.provider.network?.chainID else {
            throw Web3Error.connectionError
        }
        return UInt64(chainId)
    }

    func signMessage(message: String) async throws -> String {
        let messageData = message.data(using: .utf8)!
        let signature = try web3.wallet.signPersonalMessage(
            messageData,
            account: address,
            password: ""  // Or prompt user
        )
        return signature.toHexString().addHexPrefix()
    }

    func signTypedData(typedDataJson: String) async throws -> String {
        // Parse typed data and sign
        let data = typedDataJson.data(using: .utf8)!
        let typedData = try JSONDecoder().decode(EIP712TypedData.self, from: data)

        let signature = try web3.wallet.signTypedData(
            typedData,
            account: address,
            password: ""
        )
        return signature.toHexString().addHexPrefix()
    }

    func sendTransaction(toAddress: String, value: String, data: String) async throws -> String {
        var transaction = EthereumTransaction(
            to: EthereumAddress(toAddress)!,
            value: BigUInt(value)!,
            data: Data(hex: data)
        )

        let result = try web3.eth.sendTransaction(transaction)
        return result.hash
    }

    func waitForTransactionReceipt(txHash: String) async throws -> TransactionReceipt {
        // Poll eth_getTransactionReceipt via your web3 provider until it returns a receipt.
        return try await pollReceipt(txHash: txHash)
    }
}

Testing with Mock Wallet

For testing, create a mock delegate:

class MockWalletDelegate: WalletDelegate {
    let mockAddress = "0x1234567890123456789012345678901234567890"
    let mockChainId: UInt64 = 1

    var signMessageHandler: ((String) -> String)?
    var signTypedDataHandler: ((String) -> String)?
    var sendTransactionHandler: ((String, String, String) -> String)?

    func getAddress() async throws -> String {
        return mockAddress
    }

    func getChainId() async throws -> UInt64 {
        return mockChainId
    }

    func signMessage(message: String) async throws -> String {
        if let handler = signMessageHandler {
            return handler(message)
        }
        // Return a valid-looking signature
        return "0x" + String(repeating: "ab", count: 65)
    }

    func signTypedData(typedDataJson: String) async throws -> String {
        if let handler = signTypedDataHandler {
            return handler(typedDataJson)
        }
        return "0x" + String(repeating: "cd", count: 65)
    }

    func sendTransaction(toAddress: String, value: String, data: String) async throws -> String {
        if let handler = sendTransactionHandler {
            return handler(toAddress, value, data)
        }
        return "0x" + String(repeating: "ef", count: 32)
    }

    func waitForTransactionReceipt(txHash: String) async throws -> TransactionReceipt {
        return TransactionReceipt(txHash: txHash, status: true, logs: [])
    }
}

Error Handling

Throw appropriate errors from delegate methods:

enum WalletDelegateError: Error, LocalizedError {
    case notConnected
    case userRejected
    case networkError(String)
    case invalidSignature
    case transactionFailed(String)

    var errorDescription: String? {
        switch self {
        case .notConnected:
            return "Wallet not connected"
        case .userRejected:
            return "User rejected the request"
        case .networkError(let message):
            return "Network error: \(message)"
        case .invalidSignature:
            return "Invalid signature returned"
        case .transactionFailed(let message):
            return "Transaction failed: \(message)"
        }
    }
}

Best Practices

Validate inputs - Check addresses and data formats before processing
Handle timeouts - Set reasonable timeouts for wallet operations
User feedback - Show loading indicators during signing/transactions
Error messages - Provide clear error messages for user-facing errors
Thread safety - Ensure delegate methods can be called from any thread

Next Steps

Getting Started - iOS SDK overview

Quickstart

Setup

SDKs

Wallet integration

Wallet Integration

Protocol Definition

Implementation Requirements

Return Values

Async Behavior

WalletConnect Integration

Web3.swift Integration

Testing with Mock Wallet

Error Handling

Best Practices

Next Steps

​Wallet Integration

​Protocol Definition

​Implementation Requirements

​Return Values

​Async Behavior

​WalletConnect Integration

​Web3.swift Integration

​Testing with Mock Wallet

​Error Handling

​Best Practices

​Next Steps

Wallet Integration

Protocol Definition

Implementation Requirements

Return Values

Async Behavior

WalletConnect Integration

Web3.swift Integration

Testing with Mock Wallet

Error Handling

Best Practices

Next Steps