API Reference

Complete API reference for the Privacy Boost Android SDK.

Generated Documentation

Full API documentation can be generated using cargo doc:

# From rust-sdk directory
make docs-rust

# Android-specific docs
cargo doc --no-deps -p privacy-boost-android

PrivacyBoost

Main SDK class for Android.

Constructor

PrivacyBoost(config: PrivacyBoostConfig)

Creates a new SDK instance. Parameters:

config - SDK configuration

Properties

fun isConnected(): Boolean
fun isAuthenticated(): Boolean

Connection & Authentication Methods

authenticate

fun authenticate(wallet: WalletDelegate, keySource: KeySource? = null, tokenProvider: TokenProvider? = null): AuthResult

Connect a wallet, derive privacy keys, and authenticate with the Privacy Boost backend in a single call. Parameters:

wallet - Implementation of WalletDelegate interface
keySource - Optional key derivation source. If null and no persistence is configured, defaults to KeySource.WalletDerived. If null with persistence configured and no existing vault, an error is thrown.
tokenProvider - Optional custom token provider. If null, the SDK sends the login payload directly to the Privacy Boost backend. Supply a TokenProvider to route authentication through your own server.

Returns: AuthResult - either AuthResult.Authenticated(LoginResult) or AuthResult.CredentialRequired(CredentialChallenge) Throws:

SDKError.WalletError if signing fails
SDKError.InvalidConfig if configuration is invalid or keySource is required but missing
SDKError.NetworkError if backend unreachable

submitCredential

fun submitCredential(credential: String, tokenProvider: TokenProvider? = null): LoginResult

Submit a credential when authenticate() returns CredentialRequired. Parameters:

credential - The credential string
tokenProvider - Optional custom token provider for routing authentication through your own server

Returns: LoginResult with privacy address and MPK

logout

fun logout()

End session completely, clear all state.

clearSession

fun clearSession()

Clear JWT only, keep keys for quick re-auth.

State Accessors

fun getPrivacyAddress(): String?
fun getMpk(): String?
fun getWalletAddress(): String?

Balance Methods

getBalance

fun getBalance(tokenAddress: String): TokenBalance

Get balance for a specific token. Parameters:

tokenAddress - ERC-20 token contract address

Returns: TokenBalance with shielded and wallet amounts

getAllBalances

fun getAllBalances(): List<TokenBalance>

Get all token balances.

Vault Operations

deposit

fun deposit(tokenAddress: String, amount: String): DepositResult

Deposit tokens into the shielded pool. Parameters:

tokenAddress - Token contract address
amount - Amount in wei (as string)

Returns: DepositResult with transaction hash

withdraw

fun withdraw(tokenAddress: String, amount: String, recipient: String): UnshieldResult

Withdraw tokens from the shielded pool. Parameters:

tokenAddress - Token contract address
amount - Amount in wei (as string)
recipient - Recipient Ethereum address

Returns: UnshieldResult with transaction hash

send

fun send(tokenAddress: String, amount: String, recipientPrivacyAddress: String): TransferResult

Send a private transfer. Parameters:

tokenAddress - Token contract address
amount - Amount in wei (as string)
recipientPrivacyAddress - Recipient’s 194-char privacy address

Returns: TransferResult with transaction hash

Transaction History

fun getTransactionHistory(
    txType: String?,
    tokenAddress: String?,
    limit: UInt?
): List<Transaction>

Get transaction history. Parameters:

txType - Filter by type: “deposit”, “withdraw”, “transfer”
tokenAddress - Filter by token
limit - Maximum results

Session Persistence

exportSession

fun exportSession(): ExportedSession?

Export session data for persistence. Returns: ExportedSession or null if not authenticated

importSession

fun importSession(session: ExportedSession): Boolean

Import a previously exported session. Returns: true if session is valid and imported

Address Lookup

resolveIdentity

fun resolveIdentity(identifier: String): IdentityResult

Look up a user’s privacy address by MPK or Ethereum address. Parameters:

identifier - MPK or Ethereum address

Returns: IdentityResult with privacy address and public keys

Utilities

fun isValidPrivacyAddress(address: String): Boolean
fun isValidAddress(address: String): Boolean
fun parseAmount(amount: String, decimals: UByte): String
fun formatAmount(wei: String, decimals: UByte): String

Module Functions

fun sdkVersion(): String
fun generateMnemonic(): String

sdkVersion() — Returns the SDK version string
generateMnemonic() — Generates a random 12-word BIP-39 mnemonic

Types

PrivacyBoostConfig

data class PrivacyBoostConfig(
    val serverUrl: String,
    val wethContractAddress: String,
    val appId: String,
    val chainId: ULong? = null,
    val shieldContractAddress: String? = null,
    val teePublicKey: String? = null
)

KeySource

sealed class KeySource {
    object WalletDerived : KeySource()
    data class Mnemonic(val phrase: String) : KeySource()
    data class RawSeed(val hexSeed: String) : KeySource()
}

Specifies how privacy keys are derived. Passed as an optional parameter to authenticate().

WalletDerived - Derive keys from a deterministic wallet signature (default when no persistence configured)
Mnemonic - Derive keys from a BIP-39 mnemonic phrase
RawSeed - Derive keys from raw hex entropy (for testing)

AuthResult

sealed class AuthResult {
    data class Authenticated(val loginResult: LoginResult) : AuthResult()
    data class CredentialRequired(val challenge: CredentialChallenge) : AuthResult()
}

LoginResult

data class LoginResult(
    val privacyAddress: String,
    val mpk: String
)

TokenBalance

data class TokenBalance(
    val tokenAddress: String,
    val shieldedBalance: String,
    val walletBalance: String,
    val symbol: String?,
    val decimals: UByte
)

DepositResult

data class DepositResult(
    val txHash: String,
    val commitment: String,
    val fee: String
)

UnshieldResult

data class UnshieldResult(
    val txHash: String,
    val fee: String
)

TransferResult

data class TransferResult(
    val txHash: String,
    val fee: String
)

Transaction

data class Transaction(
    val txHash: String,
    val txType: String,
    val tokenAddress: String,
    val amount: String,
    val direction: String,
    val senderPubKey: String,
    val receiverPubKeys: List<String>,
    val createdAt: ULong
)

IdentityResult

data class IdentityResult(
    val mpk: String,
    val ethereumAddress: String,
    val viewingPublicKeyX: String,
    val viewingPublicKeyY: String,
    val privacyAddress: String
)

ExportedSession

data class ExportedSession(
    val walletPublicKeyX: String,
    val walletPublicKeyY: String,
    val viewingKey: String,
    val viewingPublicKeyX: String,
    val viewingPublicKeyY: String,
    val nullifyingKey: String,
    val nullifyingPublicKeyX: String,
    val nullifyingPublicKeyY: String,
    val mpk: String,
    val accountId: String,
    val jwt: String,
    val jwtExpiry: ULong,
    val walletAddress: String
)

WalletDelegate Interface

interface WalletDelegate {
    suspend fun getAddress(): String
    suspend fun getChainId(): ULong
    suspend fun signMessage(message: String): String
    suspend fun signTypedData(typedDataJson: String): String
    suspend fun sendTransaction(toAddress: String, value: String, data: String): String
}

TokenProvider Interface

interface TokenProvider {
    suspend fun getToken(loginPayloadJson: String): TokenResponse
}

Implement this interface to route authentication through your own server. The SDK serializes the login payload as a JSON string and passes it to getToken(). Your implementation should forward this payload to your backend, which adds its own credentials and calls the Privacy Boost API.

TokenResponse

data class TokenResponse(
    val token: String,     // JWT access token
    val expiresIn: ULong   // Token lifetime in seconds
)

Example

class MyTokenProvider : TokenProvider {
    override suspend fun getToken(loginPayloadJson: String): TokenResponse {
        val response = yourHttpClient.post("https://your-server.com/api/privacy-auth") {
            contentType(ContentType.Application.Json)
            setBody(loginPayloadJson)
        }
        val json = Json.parseToJsonElement(response.bodyAsText()).jsonObject
        return TokenResponse(
            token = json["token"]!!.jsonPrimitive.content,
            expiresIn = json["expiresIn"]!!.jsonPrimitive.long.toULong()
        )
    }
}

val result = sdk.authenticate(
    wallet = walletDelegate,
    tokenProvider = MyTokenProvider()
)

SDKError

sealed class SDKError : Exception() {
    object NotConnected : SDKError()
    object NotAuthenticated : SDKError()
    object InvalidConfig : SDKError()
    data class NetworkError(override val message: String) : SDKError()
    data class WalletError(override val message: String) : SDKError()
    object SignatureRejected : SDKError()
    object InsufficientBalance : SDKError()
    object InvalidAddress : SDKError()
    object InvalidAmount : SDKError()
    data class SerializationError(override val message: String) : SDKError()
    data class AuthServerError(val code: String, override val message: String) : SDKError()
    data class DepositError(val code: String, override val message: String) : SDKError()
    data class TransferError(val code: String, override val message: String) : SDKError()
    data class NoteError(val code: String, override val message: String) : SDKError()
    data class MerkleError(val code: String, override val message: String) : SDKError()
    data class ApiError(val code: String, override val message: String, val retryable: Boolean) : SDKError()
    data class RateLimited(val retryAfterMs: ULong) : SDKError()
    data class Forbidden(override val message: String) : SDKError()
    data class ResourceNotFound(override val message: String) : SDKError()
    data class InternalError(override val message: String) : SDKError()
}

Quickstart

Setup

SDKs

Documentation Index

​API Reference

​Generated Documentation

​PrivacyBoost

​Constructor

​Properties

​Connection & Authentication Methods

​authenticate

​submitCredential

​logout

​clearSession

​State Accessors

​Balance Methods

​getBalance

​getAllBalances

​Vault Operations

​deposit

​withdraw

​send

​Transaction History

​Session Persistence

​exportSession

​importSession

​Address Lookup

​resolveIdentity

​Utilities

​Module Functions

​Types

​PrivacyBoostConfig

​KeySource

​AuthResult

​LoginResult

​TokenBalance

​DepositResult

​UnshieldResult

​TransferResult

​Transaction

​IdentityResult

​ExportedSession

​WalletDelegate Interface

​TokenProvider Interface

​TokenResponse

​Example

​SDKError

​See Also