Skip to main content

​
Getting Started

This guide walks you through integrating the Privacy Boost Android SDK into your app.
For a minimal copy-paste example, see the Android Quickstart. This guide explains each step in detail.

​
Prerequisites

​
Overview

The Android SDK follows a simple flow:
  1. Initialize - Create SDK instance with configuration
  2. Authenticate - Connect wallet and authenticate via WalletDelegate
  3. Use - Deposit, unshield, transfer tokens

​
Basic Setup

​
1. Configure the SDK

import com.privacyboost.sdk.*

val config = PrivacyBoostConfig(
    serverUrl = "https://optimism.sepolia.privacyboost.io",
    wethContractAddress = "0x4200000000000000000000000000000000000006",
    appId = "app_abc123xyz"
)

​
2. Initialize

val sdk = PrivacyBoost(config)

​
Connecting a Wallet

The SDK uses the WalletDelegate interface to interact with wallets: 
import com.privacyboost.sdk.*

class MyWalletDelegate : WalletDelegate {
    override suspend fun getAddress(): String {
        // Return the connected wallet address
        return "0x..."
    }

    override suspend fun getChainId(): ULong {
        // Return the current chain ID
        return 1UL
    }

    override suspend fun signMessage(message: String): String {
        // Sign using EIP-191 personal_sign
        // Return signature as hex string with 0x prefix
        return "0x..."
    }

    override suspend fun signTypedData(typedDataJson: String): String {
        // Sign using EIP-712 eth_signTypedData_v4
        return "0x..."
    }

    override suspend fun sendTransaction(toAddress: String, value: String, data: String): String {
        // Submit transaction and return hash
        return "0x..."
    }
}
Then authenticate: 
val wallet = MyWalletDelegate()
try {
    // Default (wallet-derived keys)
    val result = sdk.authenticate(wallet = wallet)

    // Or with a specific key source
    // val result = sdk.authenticate(
    //     wallet = wallet,
    //     keySource = KeySource.Mnemonic(phrase = "your twelve word mnemonic ...")
    // )

    when (result) {
        is AuthResult.Authenticated -> {
            println("Privacy Address: ${result.loginResult.privacyAddress}")
            println("MPK: ${result.loginResult.mpk}")
        }
        is AuthResult.CredentialRequired -> {
            // Handle credential challenge
            val loginResult = sdk.submitCredential(credential)
            println("Privacy Address: ${loginResult.privacyAddress}")
        }
    }
} catch (e: SDKError) {
    println("Authentication failed: ${e.message}")
}

​
Core Operations

​
Check Balance

try {
    val balance = sdk.getBalance("0x...")
    println("Shielded: ${balance.shieldedBalance}")
    println("Wallet: ${balance.walletBalance}")
} catch (e: SDKError) {
    println("Failed to get balance: ${e.message}")
}

​
Deposit Tokens

Move tokens from wallet to shielded pool: 
try {
    val result = sdk.shield(
        tokenAddress = "0x...",
        amount = "1000000000000000000"  // 1 token (18 decimals)
    )
    println("Deposit TX: ${result.txHash}")
} catch (e: SDKError) {
    println("Deposit failed: ${e.message}")
}

​
Withdraw Tokens

Move tokens from shielded pool to wallet: 
try {
    val result = sdk.unshield(
        tokenAddress = "0x...",
        amount = "500000000000000000",
        recipient = "0x..."  // Recipient address
    )
    println("Withdraw TX: ${result.txHash}")
} catch (e: SDKError) {
    println("Withdraw failed: ${e.message}")
}

​
Private Transfer

Send tokens privately to another user: 
try {
    val result = sdk.send(
        tokenAddress = "0x...",
        amount = "250000000000000000",
        recipientPrivacyAddress = "0x04..."  // 194-char privacy address
    )
    println("Transfer TX: ${result.txHash}")
} catch (e: SDKError) {
    println("Transfer failed: ${e.message}")
}

​
Using with Coroutines

The SDK methods are blocking. Use coroutines for non-blocking calls: 
import kotlinx.coroutines.*

class PrivacyBoostManager(private val sdk: PrivacyBoost) {

    suspend fun deposit(token: String, amount: String): DepositResult =
        withContext(Dispatchers.IO) {
            sdk.shield(token, amount)
        }

    suspend fun getBalance(token: String): TokenBalance =
        withContext(Dispatchers.IO) {
            sdk.getBalance(token)
        }
}

// Usage
lifecycleScope.launch {
    try {
        val result = manager.shield(token, amount)
        // Update UI on main thread
        binding.txHashText.text = result.txHash
    } catch (e: SDKError) {
        showError(e.message)
    }
}

​
Complete Example

import com.privacyboost.sdk.*
import kotlinx.coroutines.*

class PrivacyBoostRepository(config: PrivacyBoostConfig) {
    private val sdk = PrivacyBoost(config)
    private var walletDelegate: WalletDelegate? = null

    val isConnected: Boolean
        get() = sdk.isConnected()

    val isAuthenticated: Boolean
        get() = sdk.isAuthenticated()

    val privacyAddress: String?
        get() = sdk.getPrivacyAddress()

    suspend fun authenticate(wallet: WalletDelegate): AuthResult =
        withContext(Dispatchers.IO) {
            walletDelegate = wallet
            sdk.authenticate(wallet)
        }

    suspend fun deposit(token: String, amount: String): DepositResult =
        withContext(Dispatchers.IO) {
            sdk.shield(token, amount)
        }

    suspend fun withdraw(token: String, amount: String, recipient: String): UnshieldResult =
        withContext(Dispatchers.IO) {
            sdk.unshield(token, amount, recipient)
        }

    suspend fun send(token: String, amount: String, to: String): TransferResult =
        withContext(Dispatchers.IO) {
            sdk.send(token, amount, to)
        }

    suspend fun getBalance(token: String): TokenBalance =
        withContext(Dispatchers.IO) {
            sdk.getBalance(token)
        }

    fun logout() {
        sdk.logout()
        walletDelegate = null
    }
}

​
Error Handling

The SDK throws SDKError for various failure conditions: 
try {
    val result = sdk.shield(token, amount)
} catch (e: SDKError.NotConnected) {
    println("Wallet not connected")
} catch (e: SDKError.NotAuthenticated) {
    println("Not logged in")
} catch (e: SDKError.InsufficientBalance) {
    println("Insufficient balance")
} catch (e: SDKError.InvalidAmount) {
    println("Invalid amount format")
} catch (e: SDKError.WalletError) {
    println("Wallet error: ${e.message}")
} catch (e: SDKError.NetworkError) {
    println("Network error: ${e.message}")
} catch (e: SDKError) {
    println("Unknown error: ${e.message}")
}

​
Session Persistence

Save and restore sessions to avoid re-signing: 
// Export session
val session = sdk.exportSession()
session?.let {
    saveToSecureStorage(it)
}

// Import session
loadFromSecureStorage()?.let { session ->
    try {
        val success = sdk.importSession(session)
        if (success) {
            println("Session restored")
        }
    } catch (e: SDKError) {
        println("Session expired or invalid")
    }
}

​
Next Steps

Wallet Integration

Detailed WalletDelegate implementation

Session Storage

Android Keystore storage and biometric unlock

API Reference

Complete API documentation

Key Management

Key derivation, persistence options, and recovery