API Reference

Complete API reference for the Privacy Boost CLI library (Rust).

Generated Documentation

Full API documentation can be generated using cargo doc:

# From rust-sdk directory
make docs-rust

# CLI-specific docs
cargo doc --no-deps -p privacy-boost-cli

PrivacyBoostCLI

Main CLI SDK interface for Rust applications.

Constructor

pub fn new(config: CliConfig) -> Result<Self, CliError>

Creates a new CLI SDK instance. Parameters:

config - CLI configuration

Returns: Result<PrivacyBoostCLI, CliError> Example:

use privacy_boost_cli::{PrivacyBoostCLI, CliConfig};

let config = CliConfig::new(
    "https://optimism.sepolia.privacyboost.io".into(),
    0,
    String::new(),
    "https://sepolia.optimism.io".into(),
);

let sdk = PrivacyBoostCLI::new(config)?;

Connection & Authentication Methods

authenticate

pub fn authenticate(
    &self,
    private_key: &str,
    key_source: Option<KeySource>,
    token_provider: Option<&dyn TokenProvider>,
) -> Result<AuthResult, CliError>

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

private_key - Hex-encoded private key
key_source - Optional key derivation source. None defaults to WalletDerived. Options: KeySource::WalletDerived, KeySource::Mnemonic { phrase }, KeySource::RawSeed { hex_seed }
token_provider - Optional custom token provider for server-mediated auth flows

Returns: Result<AuthResult, CliError> - either Authenticated(LoginResult) or CredentialRequired(CredentialChallenge)

submit_credential

pub fn submit_credential(&self, credential: &str) -> Result<LoginResult, CliError>

Submit a credential when authenticate() returns CredentialRequired. Returns: Result<LoginResult, CliError>

logout

pub fn logout(&self)

End session completely, clear all state.

clear_session

pub fn clear_session(&self)

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

is_authenticated

pub fn is_authenticated(&self) -> bool

Check if authenticated.

State Accessors

pub fn get_privacy_address(&self) -> Option<String>
pub fn get_mpk(&self) -> Option<String>
pub fn get_wallet_address(&self) -> Option<String>
pub fn get_status(&self) -> StatusInfo

Balance Methods

get_balance

pub fn get_balance(&self, token_address: &str) -> Result<TokenBalance, CliError>

Get balance for a specific token.

get_all_balances

pub fn get_all_balances(&self) -> Result<Vec<TokenBalance>, CliError>

Get all token balances.

Vault Operations

deposit

pub fn shield(
    &self,
    token_address: &str,
    amount: &str,
) -> Result<ShieldResult, CliError>

Deposit tokens into the shielded pool. Parameters:

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

withdraw

pub fn unshield(
    &self,
    token_address: &str,
    amount: &str,
    recipient: &str
) -> Result<UnshieldResult, CliError>

Withdraw tokens from the shielded pool. Parameters:

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

send

pub fn send(
    &self,
    token_address: &str,
    amount: &str,
    recipient_privacy_address: &str
) -> Result<TransferResult, CliError>

Send a private transfer. Parameters:

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

send_batch

pub fn send_batch(
    &self,
    token_address: &str,
    recipients: &[(String, String)]
) -> Result<TransferResult, CliError>

Send one private transfer paying several recipients: one request, one fee, one set of input notes. Parameters:

token_address - Token contract address
recipients - (recipient, amount) pairs in output order, at least one. Amounts are wei strings

Shape limits: the transfer’s output count is the recipient count plus a change note, and the server only proves specific (inputs, outputs) combinations, so a longer recipient list limits how many input notes can be spent — past two recipients, at most four. Requests no enabled circuit can serve fail with UNSUPPORTED_TRANSFER_SHAPE before submission.

prepare_shield

pub fn prepare_shield(
    &self,
    token_address: &str,
    amount: &str,
    recipient: Option<&str>,
) -> Result<PreparedShield, CliError>

Build a deposit payload without submitting it — for relaying the transaction yourself (a gasless relayer, an EIP-7702 session key, or a plain raw transaction). Returns the wrap/approve/requestDeposit calldata plus the note commitment; nothing is sent on-chain. Needs an authenticated session (keys) but no wallet. After relaying, settle from the mined receipt with privacy_boost_core::operations::finalize_shield. Parameters:

token_address - Token contract address (use 0x0 for ETH)
amount - Amount in wei (as string)
recipient - Recipient privacy address; None shields to yourself

CLI subcommands prepare-shield and finalize-shield wrap these for shell use — see the Commands Reference.

list_shields_by_status

pub fn list_shields_by_status(
    &self,
    statuses: &[&str],
) -> Result<Vec<UnsettledShieldResponse>, CliError>

Find a deposit request id the app never kept. Lists the authenticated wallet’s own shield requests in the given public statuses (pending, processing, preconfirmed, completed, failed), oldest first; an empty slice asks the server for its default of pending. Served by the server, so it needs no chain access. Returns: UnsettledShieldResponse per row — request_id, status, and the optional tx_hash, block_number, created_at, updated_at and error.

deposit_request_ids_from_transaction

pub fn deposit_request_ids_from_transaction(
    &self,
    tx_hash: &str,
) -> Result<Vec<String>, CliError>

The fallback when the app has the shield’s transaction hash but not its request id. Reads the receipt and returns every DepositRequested id the pool emitted, in log order — more than one when an aggregating relayer settled several callers in one transaction. Empty means the transaction emitted no DepositRequested from the configured pool.

CLI subcommands deposit list and deposit ids wrap these for shell use. See the Commands Reference.

get_deposit_cancellation

pub fn get_deposit_cancellation(
    &self,
    deposit_request_id: &str,
) -> Result<DepositCancellation, CliError>

Report whether a stuck shield deposit can be cancelled right now. A shield whose deposit never settles into the note tree leaves the tokens escrowed in the pool. get_shield_status will tell you the shield failed, but nothing server-side describes the escrow behind it — whether the pool still holds it, who may reclaim it, and when — so this reads the pool directly through the connected wallet. Costs three eth_calls plus one eth_blockNumber. Parameters:

deposit_request_id - The DepositRequested event’s indexed topic1, a uint256. It’s the same request id a shield reports. Decimal or 0x-hex; the result normalizes it to decimal.

Returns: DepositCancellation with the escrowed amount, the block the delay expires at, and a reason you can print as-is

cancel_deposit

pub fn cancel_deposit(&self, deposit_request_id: &str) -> Result<String, CliError>

Cancel a stuck shield deposit, refunding its full escrowed amount to the depositor. Returns the transaction hash. Preflights the same checks as get_deposit_cancellation and fails locally, before anything is signed, when the pool would revert. The error carries the status reason, so a deposit that can’t be cancelled reports why instead of burning gas on an opaque revert. If the wallet can’t run the preflight, the transaction is submitted anyway and the chain arbitrates. Only the address that submitted the deposit can cancel it, and the refund goes to that address. For a relayer-submitted shield that’s the relayer, not the note recipient.

CLI subcommands deposit status and deposit cancel wrap these for shell use. See the Commands Reference.

Transaction History

pub fn get_transaction_history(
    &self,
    tx_type: Option<&str>,
    token_address: Option<&str>,
    limit: Option<u32>
) -> Result<Vec<Transaction>, CliError>

Get transaction history.

Session Persistence

export_session

pub fn export_session(&self) -> Option<ExportedSession>

Export session data for persistence.

import_session

pub fn import_session(&self, session: &ExportedSession) -> Result<bool, CliError>

Import session from persistence.

Address Lookup

resolve_identity

pub fn resolve_identity(&self, identifier: &str) -> Result<IdentityResult, CliError>

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

identifier - MPK or Ethereum address

Returns: Result<IdentityResult, CliError>

Utilities

pub fn is_valid_privacy_address(&self, address: &str) -> bool
pub fn is_valid_address(&self, address: &str) -> bool
pub fn parse_amount(&self, amount: &str, decimals: u8) -> Result<String, CliError>
pub fn format_amount(&self, wei: &str, decimals: u8) -> Result<String, CliError>

Module Functions

pub fn sdk_version() -> String

Returns the SDK version string.

CliConfig

CLI configuration struct.

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PrivacyBoostConfig {
    pub server_url: String,
    #[serde(default)]
    pub chain_id: u64,                        // 0 = auto-discover from server
    #[serde(default)]
    pub shield_contract_address: String,      // empty = auto-discover from server
    pub weth_contract_address: Option<String>,
    pub rpc_url: String,
    pub timeout_secs: u64,
    pub app_id: Option<String>,
    pub tee_public_key: Option<String>,
    pub persistence_storage: Option<String>,
    pub persistence_unlock: Option<String>,
}

Constructor

pub fn new(
    server_url: String,
    chain_id: u64,
    shield_contract_address: String,
    rpc_url: String,
) -> Self

Builder Methods

pub fn with_weth_contract_address(self, weth_contract_address: String) -> Self
pub fn with_timeout(self, timeout_secs: u64) -> Self

File Operations

pub fn default_config_path() -> Result<PathBuf, CliError>
pub fn load_from_file(path: &PathBuf) -> Result<Self, CliError>
pub fn load_from_default() -> Result<Option<Self>, CliError>
pub fn save_to_file(&self, path: &PathBuf) -> Result<(), CliError>
pub fn save_to_default(&self) -> Result<PathBuf, CliError>

Environment

pub fn from_environment() -> Self

NetworkPreset

Network preset enumeration.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NetworkPreset {
    Local,
    OpSepolia,
}

Methods

pub fn config(&self) -> CliConfig
pub fn parse(s: &str) -> Option<Self>

Parse aliases:

Local: "local", "localhost", "dev"
OpSepolia: "op-sepolia", "optimism-sepolia", "opsepolia"

Example:

let preset = NetworkPreset::parse("op-sepolia").unwrap();
let config = preset.config();

Types

KeySource

pub enum KeySource {
    WalletDerived,
    Mnemonic { phrase: String },
    RawSeed { hex_seed: String },
}

Key derivation source, passed to authenticate(). WalletDerived derives keys from a wallet signature, Mnemonic from a BIP-39 phrase, and RawSeed from a raw 32-byte hex seed.

AuthResult

pub enum AuthResult {
    Authenticated(LoginResult),
    CredentialRequired(CredentialChallenge),
}

LoginResult

pub struct LoginResult {
    pub wallet_address: String,
    pub privacy_address: String,
    pub mpk: String,
}

TokenBalance

pub struct TokenBalance {
    pub token_address: String,
    pub shielded_balance: String,
    pub wallet_balance: String,
    pub symbol: Option<String>,
    pub decimals: u8,
}

ShieldResult

pub struct ShieldResult {
    pub tx_hash: String,
    pub commitment: String,
}

UnshieldResult

pub struct UnshieldResult {
    pub tx_hash: String,
    pub fee: String,
}

TransferResult

pub struct TransferResult {
    pub tx_hash: String,
    pub fee: String,
}

PreparedShield

Returned by prepare_shield. Re-exported from privacy_boost_core::operations. Carries no private material, so it is safe to hand to a relayer. Each Call is a single on-chain call to relay; value and data are 0x-hex.

pub struct Call {
    pub to: String,
    pub value: String,    // 0x-hex wei quantity ("0x0" for non-payable calls)
    pub data: String,     // ABI-encoded calldata (0x-prefixed)
}

pub struct ShieldFinalizeMeta {
    pub shield_contract: String,   // the DepositRequested emitter
    pub token_id: u16,
}

pub struct PreparedShield {
    pub approve: Option<Call>,     // ERC-20 approve(pool, amount); omitted when suppressed
    pub wrap: Option<Call>,        // WETH deposit() wrap; present only for native ETH
    pub shield: Call,              // the requestDeposit(...) call
    pub commitment: String,
    pub finalize: ShieldFinalizeMeta,
}

DepositCancellation

Returned by get_deposit_cancellation. Re-exported from privacy_boost_core::operations. Amounts are decimal strings and blocks are absolute chain heights. DepositCancelState mirrors the reverts in the pool’s cancelDeposit, reported permanent-blocker first rather than in the pool’s own check order: the pool checks the depositor before anything else, and that check would mask the two conditions no caller can clear. A gateway-origin deposit stores the gateway contract as its depositor, so it reports GatewayOrigin for every caller and at every point in the delay window — waiting never makes it cancellable.

pub enum DepositCancelState {
    Cancellable,       // every precondition holds; the transaction should land
    NotFound,          // no escrow under this id: never created, or cancelled/rescued
    NotDepositor,      // escrow exists but belongs to another address
    AlreadyProcessed,  // already settled into the note tree; funds are in a note
    TooEarly,          // reclaimable, but the cancel delay has not elapsed
    GatewayOrigin,     // needs rescueGatewayDeposit by the rescue authority instead
}

pub struct DepositCancellation {
    pub deposit_request_id: String,   // the queried id, normalized to decimal
    pub state: DepositCancelState,
    pub cancellable: bool,            // true exactly when state is Cancellable
    pub depositor: Option<String>,    // None when no escrow exists
    pub caller: String,               // the address the status was evaluated against
    pub token_id: u16,
    pub total_amount: String,         // escrow that would be refunded; "0" when absent
    pub request_block: u64,
    pub cancel_delay: u64,            // the pool's cancelDelay(), in blocks
    pub cancellable_at_block: u64,    // request_block + cancel_delay
    pub current_block: u64,           // chain head the status was evaluated at
    pub blocks_remaining: u64,        // 0 once the delay has elapsed
    pub reason: String,               // human-readable explanation of state
}

The cancel delay is measured in blocks and read from the pool’s cancelDelay(). Read the deployed value instead of hardcoding a delay, using cancel_delay, cancellable_at_block, and blocks_remaining from the status.

Transaction

pub struct Transaction {
    pub tx_hash: String,
    pub tx_type: String,
    pub token_address: String,
    pub amount: String,
    pub direction: String,
    pub sender_pub_key: String,
    pub receiver_pub_keys: Vec<String>,
    pub created_at: u64,
}

StatusInfo

pub struct StatusInfo {
    pub connected: bool,
    pub authenticated: bool,
    pub wallet_address: Option<String>,
    pub privacy_address: Option<String>,
    pub mpk: Option<String>,
}

IdentityResult

pub struct IdentityResult {
    pub mpk: String,
    pub ethereum_address: String,
    pub viewing_public_key_x: String,
    pub viewing_public_key_y: String,
    pub privacy_address: String,
}

ExportedSession

Re-exported from privacy_boost_core::sdk_state::ExportedSession:

pub struct ExportedSession {
    pub wallet_public_key_x: String,
    pub wallet_public_key_y: String,
    pub viewing_key: String,
    pub viewing_public_key_x: String,
    pub viewing_public_key_y: String,
    pub nullifying_key: String,
    pub nullifying_public_key_x: String,
    pub nullifying_public_key_y: String,
    pub mpk: String,
    pub account_id: String,
    pub jwt: String,
    pub jwt_expiry: u64,
    pub wallet_address: String,
}

CliError

pub enum CliError {
    NotConnected,
    NotAuthenticated,
    InvalidConfig { message: String },
    InvalidPrivateKey { message: String },
    NetworkError { message: String },
    WalletError { message: String },
    SigningError { message: String },
    TransactionFailed { message: String },
    InsufficientBalance,
    InvalidAddress,
    InvalidAmount,
    SerializationError { message: String },
    InternalError { message: String },
    ConfigFileError { message: String },
}

Default Values

pub mod defaults {
    pub const RPC_URL: &str = "http://localhost:8545";
    pub const SERVER_URL: &str = "http://localhost:8080";
    pub const WETH_CONTRACT_ADDRESS: &str = "0x36c02da8a0983159322a80ffe9f24b1acff8b570";
    pub const TEST_TOKEN_CONTRACT: &str = "0x36c02da8a0983159322a80ffe9f24b1acff8b570";
}

Complete Example

use privacy_boost_cli::{PrivacyBoostCLI, CliConfig, NetworkPreset};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load configuration from preset
    let config = NetworkPreset::OpSepolia.config();

    // Or load from file
    // let config = CliConfig::load_from_default()?.unwrap();

    // Create SDK
    let sdk = PrivacyBoostCLI::new(config)?;

    // Authenticate with private key
    let private_key = std::env::var("PRIVATE_KEY")?;
    let auth_result = sdk.authenticate(&private_key, None, None)?;
    match auth_result {
        AuthResult::Authenticated(login_result) => {
            println!("Privacy Address: {}", login_result.privacy_address);
        }
        AuthResult::CredentialRequired(challenge) => {
            let login_result = sdk.submit_credential(&credential)?;
            println!("Privacy Address: {}", login_result.privacy_address);
        }
    }

    // Check balance
    let token = "0x4200000000000000000000000000000000000006";
    let balance = sdk.get_balance(token)?;
    println!("Balance: {} wei", balance.shielded_balance);

    // Deposit
    let deposit_result = sdk.shield(token, "1000000000000000000")?;
    println!("Deposit TX: {}", deposit_result.tx_hash);

    // Export session for later
    if let Some(session) = sdk.export_session() {
        let json = serde_json::to_string(&session)?;
        std::fs::write("session.json", json)?;
    }

    // Logout
    sdk.logout();

    Ok(())
}

Gift & Portal Commands

Claimable transfers and portal deposit addresses are exposed as CLI subcommands:

Claimable Transfers — gift-fund-to-wallet, gift-fund, gift-list, gift-claim, gift-claim-from-link, gift-refund-by-record, gift-refund, gift-decode-link
Portal Deposits — portal create | list | status | deposits | sweep | reclaim | withdraw

​API Reference

​Generated Documentation

​PrivacyBoostCLI

​Constructor

​Connection & Authentication Methods

​authenticate

​submit_credential

​logout

​clear_session

​is_authenticated

​State Accessors

​Balance Methods

​get_balance

​get_all_balances

​Vault Operations

​deposit

​withdraw

​send

​send_batch

​prepare_shield

​list_shields_by_status

​deposit_request_ids_from_transaction

​get_deposit_cancellation

​cancel_deposit

​Transaction History

​Session Persistence

​export_session

​import_session

​Address Lookup

​resolve_identity

​Utilities

​Module Functions

​CliConfig

​Constructor

​Builder Methods

​File Operations

​Environment

​NetworkPreset

​Methods

​Types

​KeySource

​AuthResult

​LoginResult

​TokenBalance

​ShieldResult

​UnshieldResult

​TransferResult

​PreparedShield

​DepositCancellation

​Transaction

​StatusInfo

​IdentityResult

​ExportedSession

​CliError

​Default Values

​Complete Example

​Gift & Portal Commands

​See Also

API Reference

Generated Documentation

PrivacyBoostCLI

Constructor

Connection & Authentication Methods

authenticate

submit_credential

logout

clear_session

is_authenticated

State Accessors

Balance Methods

get_balance

get_all_balances

Vault Operations

deposit

withdraw

send

send_batch

prepare_shield

list_shields_by_status

deposit_request_ids_from_transaction

get_deposit_cancellation

cancel_deposit

Transaction History

Session Persistence

export_session

import_session

Address Lookup

resolve_identity

Utilities

Module Functions

CliConfig

Constructor

Builder Methods

File Operations

Environment

NetworkPreset

Methods

Types

KeySource

AuthResult

LoginResult

TokenBalance

ShieldResult

UnshieldResult

TransferResult

PreparedShield

DepositCancellation

Transaction

StatusInfo

IdentityResult

ExportedSession

CliError

Default Values

Complete Example

Gift & Portal Commands

See Also