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 shield(tokenAddress: String, amount: String): ShieldResult

Deposit tokens into the shielded pool. Parameters:

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

Returns: ShieldResult with transaction hash

withdraw

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

prepareShield

fun prepareShield(tokenAddress: String, amount: String, recipient: String?): PreparedShield

Build a deposit payload without submitting it — for callers that relay the transaction themselves (a gasless relayer, an EIP-7702 session key, or a plain raw transaction). Returns the calldata to relay plus the note commitment; nothing is sent on-chain and no wallet is used. After relaying, pass the mined receipt to the top-level finalizeShield(...) to recover the on-chain request id. Parameters:

tokenAddress - Token contract address (zero address = native ETH)
amount - Amount in wei (as string)
recipient - (Optional) recipient privacy address. Pass null to shield to yourself.

Returns: PreparedShield with the calls to relay and the note commitment

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

Stateless shield helpers

Top-level functions for building a deposit payload without a signed-in session — for a backend that holds only a recipient’s privacy address. No wallet, no private keys.

fun buildShieldPayload(
    tokenAddress: String,
    amount: String,
    recipient: String,
    tokenId: UShort,
    shieldContractAddress: String,
    wethContractAddress: String?,
    teePublicKey: String,
    minShieldAmount: String?,
    emitApprove: Boolean
): PreparedShield

fun finalizeShield(
    receipt: TransactionReceipt,
    shieldContract: String,
    commitment: String
): ShieldResult

buildShieldPayload builds a recipient-targeted deposit payload from public material only. Resolve tokenId, shieldContractAddress, and teePublicKey from the token catalog / config. An ephemeral sender keypair is generated and discarded internally, and the note is spendable only by recipient. wethContractAddress is required only when shielding native ETH; minShieldAmount (per-token minimum in wei) rejects below-minimum deposits; emitApprove emits the ERC-20 approve call (pass true by default). finalizeShield recovers the on-chain shield request id from the mined receipt of a relayed deposit. Stateless — the caller obtained the receipt from its own relay/RPC. Throws if the deposit reverted or the DepositRequested log is absent.

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
)

ShieldResult

Returned by shield and finalizeShield.

data class ShieldResult(
    val txHash: String,
    val commitment: String,
    val warning: String?,
    val requestId: String,      // on-chain shield request id
    val wrapTxHash: String?     // present when native ETH was wrapped
)

UnshieldResult

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

TransferResult

data class TransferResult(
    val requestId: String,
    val txHash: String,
    val fee: String,
    val giftRecord: GiftRecord?, // populated by gift funding; null for an ordinary send()
    val claimLink: String?       // pbgift:v1:... populated by gift funding
)

Call

A single on-chain call to relay. value and data are 0x-hex.

data class Call(
    val to: String,
    val value: String,
    val data: String
)

PreparedShield

Returned by prepareShield and buildShieldPayload.

data class ShieldFinalizeMeta(
    val shieldContract: String,
    val tokenId: UShort
)

data class PreparedShield(
    val approve: Call?,   // ERC-20 approve(pool, amount); null when managed out of band
    val wrap: Call?,      // WETH deposit() wrap; present only when shielding native ETH
    val shield: Call,     // the requestDeposit(...) call
    val commitment: String,
    val finalize: ShieldFinalizeMeta
)

TransactionReceipt

The mined-receipt type passed to finalizeShield.

data class TransactionLog(
    val address: String,
    val topics: List<String>,
    val data: String
)

data class TransactionReceipt(
    val txHash: String,
    val status: Boolean,
    val logs: List<TransactionLog>
)

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 version: UInt,
    val data: String
)

data is an opaque serialized core session. Store and pass it back unchanged; do not parse or persist individual key fields.

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
    suspend fun waitForTransactionReceipt(txHash: String): TransactionReceipt
}

data class TransactionLog(
    val address: String,
    val topics: List<String>,
    val data: String
)

data class TransactionReceipt(
    val txHash: String,
    val status: Boolean,
    val logs: List<TransactionLog>
)

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()
    data class AuthenticationFailed(override val message: String) : SDKError()
    object InvalidConfig : SDKError()
    data class ConfigError(override val message: String) : SDKError()
    data class NetworkError(override val message: String) : SDKError()
    data class WalletError(override val message: String) : SDKError()
    object SignatureRejected : SDKError()
    data class InsufficientBalance(override val message: String) : SDKError()
    object InvalidAddress : SDKError()
    object InvalidAmount : SDKError()
    data class InvalidInput(override val message: String) : SDKError()
    data class SerializationError(override val message: String) : SDKError()
    data class AuthServerError(val code: String, override val message: String) : SDKError()
    data class ShieldError(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 WaitTimeout(val requestId: String, val waited: String) : SDKError()
    data class TransactionFailed(val requestId: String, override val message: String) : SDKError()
    data class InternalError(override val message: String) : SDKError()
    data class TransactionReverted(override val message: String) : SDKError()
    data class CryptoError(override val message: String) : SDKError()
    data class StateError(override val message: String) : SDKError()
    data class OperationError(override val message: String) : SDKError()
}

Gift Methods

Claimable-transfer (gift) methods on the PrivacyBoost instance. Preview feature — pending external audit, enabled per deployment. See the Claimable Transfers guide for usage and the concept page for the trust model. Suspend methods should be called inside withContext(Dispatchers.IO).

giftFundToWallet

fun giftFundToWallet(
    tokenAddress: String,
    amount: String,
    recipientWallet: String,
    refundAfterBlock: ULong,
    currentBlock: ULong
): TransferResult

Fund a gift bound to a recipient wallet address that may not be registered yet. Parameters:

tokenAddress - Token contract address
amount - Amount in wei (as string)
recipientWallet - Recipient’s Ethereum address the gift binds to (irrevocable)
refundAfterBlock - Block height after which an unclaimed gift may be reclaimed
currentBlock - Current chain head; pre-validates the refund delay

Returns: TransferResult with giftRecord (persist it) and claimLink

giftFund

fun giftFund(
    tokenAddress: String,
    amount: String,
    recipientPrivacyAddress: String,
    recipientWallet: String,
    refundAfterBlock: ULong,
    currentBlock: ULong
): TransferResult

Fund a gift when the recipient is already a Privacy Boost user. Seals the gift ciphertext to their viewing key for the smoothest discovery. Parameters:

tokenAddress - Token contract address
amount - Amount in wei (as string)
recipientPrivacyAddress - Recipient’s 194-char privacy address (ECDH target)
recipientWallet - Recipient’s Ethereum address the gift binds to (irrevocable)
refundAfterBlock - Block height after which an unclaimed gift may be reclaimed
currentBlock - Current chain head; pre-validates the refund delay

Returns: TransferResult with giftRecord (persist it) and claimLink

giftClaim

fun giftClaim(index: UInt, acknowledgeUnknownSender: Boolean): TransferResult

Claim a pending gift by its position in getPendingGifts(). Parameters:

index - Position in the pending-gift list
acknowledgeUnknownSender - Must be true; consents to funds from a hidden sender

giftClaimByCGift

fun giftClaimByCGift(cGift: String, acknowledgeUnknownSender: Boolean): TransferResult

Claim a pending gift by its stable commitment cGift. Preferred over index when the pending list may shift as gifts settle. Parameters:

cGift - Stable gift commitment
acknowledgeUnknownSender - Must be true

giftClaimFromLink

fun giftClaimFromLink(link: String, acknowledgeUnknownSender: Boolean): TransferResult

Claim directly from a pbgift:v1:... claim link without a server lookup first. Parameters:

link - A pbgift:v1:... claim link
acknowledgeUnknownSender - Must be true

giftRefundByRecord

fun giftRefundByRecord(index: UInt): TransferResult

Refund an unclaimed gift using the local gift record saved at funding time. Only valid after refundAfterBlock has elapsed. Parameters:

index - Position in getGiftRecords()

giftRefund

fun giftRefund(
    recipientWallet: String,
    blind: String,
    refundAfterBlock: ULong,
    tokenId: UShort,
    amount: String,
    fundingTreeNumber: ULong,
    giftLeafIndex: ULong
): TransferResult

Refund an unclaimed gift by supplying every field manually — the fallback when the local gift record has been lost.

getPendingGifts

fun getPendingGifts(): List<PendingGift>

List pending gifts addressed to the authenticated wallet (TEE discovery).

getGiftRecords

fun getGiftRecords(): List<GiftRecord>

List the local gift records the SDK persisted for gifts you funded. These are what make an unclaimed gift refundable and are included in an exported session.

decodeGiftLink

fun decodeGiftLink(link: String): GiftLinkPreview

Decode a pbgift:v1:... claim link into a preview. Synchronous and throwing — works fully offline, so it does not need withContext(Dispatchers.IO). Parameters:

link - A pbgift:v1:... claim link

Returns: GiftLinkPreview

giftFundSecretBearer(...) also exists but is experimental, disabled by default, and a bearer instrument (whoever holds the link can claim). See the concept page before considering it.

Gift Types

data class GiftRecord(
    val recipientWallet: String,
    val blind: String,
    val refundAfterBlock: ULong,
    val tokenId: UShort,
    val amount: String,
    val cGift: String,
    val giftNpk: String,
    val requestId: String,
    val fundingTreeNumber: ULong?,
    val giftLeafIndex: ULong?,
    val status: String?
)

data class PendingGift(
    val index: UInt,
    val treeNumber: ULong,
    val leafIndex: ULong,
    val cGift: String,
    val tokenId: UShort,
    val amount: String,
    val refundAfterBlock: ULong,
    val recipientWallet: String
)

data class GiftLinkPreview(
    val server: String,
    val chainId: ULong,
    val cGift: String,
    val recipientWallet: String,
    val tokenId: UShort,
    val amount: String,
    val refundAfterBlock: ULong
)

The gift fields are added to the existing TransferResult returned by the fund / claim / refund methods:

data class TransferResult(
    val requestId: String,
    val txHash: String,
    val fee: String,
    val giftRecord: GiftRecord?, // present on a fund; persist it to refund later
    val claimLink: String?       // pbgift:v1:... present on a wallet-bound fund
)

Portal

Portal deposit-address building blocks. Preview feature — pending external audit, enabled per deployment. Android exposes the low-level primitives only (no high-level portal resource); your app owns the EIP-7702 transaction orchestration. See the Portal Deposits guide for the lifecycle and the concept page for the trust model and launch limitations.

Instance Methods

publishPortalRegistry

fun publishPortalRegistry(portal: String)

Publish the private discovery registry entry so the indexer can credit deposits to the owner’s account. Suspend — call inside withContext(Dispatchers.IO). Parameters:

portal - The portal deposit address E

portalDelegateAddress

fun portalDelegateAddress(): String?

Returns the portal delegate address advertised by the server’s /info, or null if the server does not support portals.

Portal lifecycle

fun createPortal(index: UInt?): Portal
fun listPortals(): List<PortalInfo>
fun listPortalDeposits(portal: String): List<PortalDeposit>
fun getPortalStatus(portal: String): PortalStatus
fun sweepPortal(portal: String, tokenId: UShort): String
fun reclaimPortalDeposit(depositId: String): String
fun withdrawPortal(
    index: UInt,
    token: String,
    to: String,
    amount: String,
    nonce: ULong,
    gasLimit: ULong,
    maxFeePerGas: String,
    maxPriorityFeePerGas: String
): String

createPortal(index) — Derive portal E, gaslessly delegate and register it via the server relays, then publish the discovery entry. Pass null to use the next free derivation index.
listPortals() — List the authenticated account’s portals with status and derivation index.
listPortalDeposits(portal) — List deposits observed at a portal.
getPortalStatus(portal) — Return registry/on-chain status for one portal.
sweepPortal(portal, tokenId) — Send requestPortalDeposit from the connected wallet and return the transaction hash.
reclaimPortalDeposit(depositId) — Send cancelPortalDeposit from the connected wallet and return the transaction hash.
withdrawPortal(...) — Build a signed EIP-1559 transaction that withdraws raw funds resting at seed-derived portal E. Broadcast the returned raw transaction yourself.

Top-Level Functions

These package-level functions are low-level escape hatches for custodial integrations that manage their own portal EOA key. The seed-derived createPortal flow does not expose a private key.

fun generatePortalEoa(): PortalEoa
fun encodePortalWithdraw(token: String, to: String, amount: String): String

generatePortalEoa() — Generate a fresh portal address E and its secret private key for custodial integrations.
encodePortalWithdraw(token, to, amount) — Encode PortalDelegate.withdraw calldata for a custodial integration that already controls E.

Portal Types

data class Portal(
    val address: String,
    val index: UInt,
    val bindH: String
)

data class PortalInfo(
    val address: String,
    val index: UInt?,
    val status: PortalStatus
)

data class PortalStatus(
    val registered: Boolean,
    val delegated: Boolean,
    val published: Boolean
)

enum class PortalDepositState {
    PendingSweep,
    Credited,
    Cancellable,
    Cancelled,
    Unknown
}

data class PortalDeposit(
    val portalDepositId: String,
    val portal: String,
    val tokenId: UShort,
    val grossAmount: String,
    val netAmount: String,
    val state: PortalDepositState,
    val requestBlock: ULong,
    val cancellableAtBlock: ULong
)

data class PortalEoa(
    val privateKey: String, // SECRET — custody and sign with it; never persisted by the SDK
    val address: String     // the portal deposit address E
)

​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

​prepareShield

​Transaction History

​Session Persistence

​exportSession

​importSession

​Address Lookup

​resolveIdentity

​Utilities

​Module Functions

​Stateless shield helpers

​Types

​PrivacyBoostConfig

​KeySource

​AuthResult

​LoginResult

​TokenBalance

​ShieldResult

​UnshieldResult

​TransferResult

​Call

​PreparedShield

​TransactionReceipt

​Transaction

​IdentityResult

​ExportedSession

​WalletDelegate Interface

​TokenProvider Interface

​TokenResponse

​Example

​SDKError

​Gift Methods

​giftFundToWallet

​giftFund

​giftClaim

​giftClaimByCGift

​giftClaimFromLink

​giftRefundByRecord

​giftRefund

​getPendingGifts

​getGiftRecords

​decodeGiftLink

​Gift Types

​Portal

​Instance Methods

​publishPortalRegistry

​portalDelegateAddress

​Portal lifecycle

​Top-Level Functions

​Portal Types

​See Also

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

prepareShield

Transaction History

Session Persistence

exportSession

importSession

Address Lookup

resolveIdentity

Utilities

Module Functions

Stateless shield helpers

Types

PrivacyBoostConfig

KeySource

AuthResult

LoginResult

TokenBalance

ShieldResult

UnshieldResult

TransferResult

Call

PreparedShield

TransactionReceipt

Transaction

IdentityResult

ExportedSession

WalletDelegate Interface

TokenProvider Interface

TokenResponse

Example

SDKError

Gift Methods

giftFundToWallet

giftFund

giftClaim

giftClaimByCGift

giftClaimFromLink

giftRefundByRecord

giftRefund

getPendingGifts

getGiftRecords

decodeGiftLink

Gift Types

Portal

Instance Methods

publishPortalRegistry

portalDelegateAddress

Portal lifecycle

Top-Level Functions

Portal Types

See Also