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

The SDK installed in your project
An App ID and server URL (see Configuration)
A wallet integration (WalletConnect, custom, etc.)
Familiarity with authentication options (optional for development, required for production)

Overview

The Android SDK follows a simple flow:

Initialize - Create SDK instance with configuration
Authenticate - Connect wallet and authenticate via WalletDelegate
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..."
    }

    override suspend fun waitForTransactionReceipt(txHash: String): TransactionReceipt {
        // Poll eth_getTransactionReceipt until the transaction is mined
        return TransactionReceipt(txHash = txHash, status = true, logs = emptyList())
    }
}

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 shield(token: String, amount: String): ShieldResult =
        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 shield(token: String, amount: String): ShieldResult =
        withContext(Dispatchers.IO) {
            sdk.shield(token, amount)
        }

    suspend fun unshield(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

Quickstart

Setup

SDKs

Getting started

Getting Started

Prerequisites

Overview

Basic Setup

1. Configure the SDK

2. Initialize

Connecting a Wallet

Core Operations

Check Balance

Deposit Tokens

Withdraw Tokens

Private Transfer

Using with Coroutines

Complete Example

Error Handling

Session Persistence

Next Steps

Wallet Integration

Session Storage

API Reference

Key Management

​Getting Started

​Prerequisites

​Overview

​Basic Setup

​1. Configure the SDK

​2. Initialize

​Connecting a Wallet

​Core Operations

​Check Balance

​Deposit Tokens

​Withdraw Tokens

​Private Transfer

​Using with Coroutines

​Complete Example

​Error Handling

​Session Persistence

​Next Steps

Wallet Integration

Session Storage

API Reference

Key Management

Getting Started

Prerequisites

Overview

Basic Setup

1. Configure the SDK

2. Initialize

Connecting a Wallet

Core Operations

Check Balance

Deposit Tokens

Withdraw Tokens

Private Transfer

Using with Coroutines

Complete Example

Error Handling

Session Persistence

Next Steps