# Zingolib FFI Rewrite

## Overview

A **single global `LightClient` wallet instance** is managed inside Rust (stored in a global `RwLock<Option<LightClient>>`). The FFI exposes **string-based APIs** (mostly JSON strings) to:

- **Initialize / restore** a wallet (new, from seed, from UFVK, from base64 wallet bytes)
- **Persist / validate** wallet bytes (base64 encode/decode)
- **Sync / rescan** and query sync status
- **Query wallet data** (height, balance, value transfers, messages, address lists)
- **Address / key utilities** (parse address/ufvk, get UFVK/seed, detect wallet kind)
- **Send flow** as a 2-step propose/confirm (plus “shield”)
- **Tor client management** (create/remove) and optional price fetch via Tor
- **Misc** (server info, change server, version strings, donation addresses, crypto provider)

All throwing functions may throw `ZingolibError`:

- `LightclientNotInitialized` (wallet not initialized yet)
- `LightclientLockPoisoned` (global lock poisoned)
- `Panic` (panic captured and returned as error text)

---

## API surface

### Logging / runtime setup

* `string init_logging() throws ZingolibError`
Initializes Android logging (no-op on iOS). Returns `"OK"`.

* `string set_crypto_default_provider_to_ring() throws ZingolibError`
Ensures Rustls default crypto provider is installed (ring). Returns `"true"` or `"Error: ..."`.

---

### Wallet initialization / restoration, creates the global LightClient

- `string init_new(string serveruri, string chainhint, string performancelevel, u32 minconfirmations) throws ZingolibError`
- Creates a new wallet and lightclient, using latest block from `serveruri` (wallet starts at `latest_height - 100`). Returns **recovery info** (same as `get_seed()`).

- `string init_from_seed(string seed, u32 birthday, string serveruri, string chainhint, string performancelevel, u32 minconfirmations) throws ZingolibError`
- Restores wallet from BIP-39 mnemonic phrase and birthday height. Returns **recovery info** (same as `get_seed()`).

- `string init_from_ufvk(string ufvk, u32 birthday, string serveruri, string chainhint, string performancelevel, u32 minconfirmations) throws ZingolibError`
- Restores wallet from a Unified Full Viewing Key + birthday. Returns **UFVK JSON** (same format as `get_ufvk()`).

- `string init_from_b64(string datab64, string serveruri, string chainhint, string performancelevel, u32 minconfirmations) throws ZingolibError`
- Restores wallet from base64-encoded wallet bytes. Returns either **recovery info** (if mnemonic present) or **UFVK JSON** (if watch-only).

---

### Wallet persistence / validation

- `string save_to_b64() throws ZingolibError`
Serializes wallet bytes and returns **base64 (padded)**. May return empty string if “save not required”.

- `string check_b64(string datab64)`
Returns `"true"` if base64 decodes successfully, else `"false"`.

- `string get_wallet_save_required() throws ZingolibError`
Returns JSON: `{ "save_required": bool }`.

- `string get_wallet_version() throws ZingolibError`
Returns JSON: `{ "current_version": ..., "read_version": ... }`.

---

### Server / chain info

- `string get_latest_block_server(string serveruri) throws ZingolibError`
Queries a lightwalletd server and returns the latest block height as a string, or `"Error: ..."`.

- `string get_latest_block_wallet() throws ZingolibError`
Returns JSON: `{ "height": wallet_height_or_0 }`.

- `string info_server() throws ZingolibError`
Returns server info string from `lightclient.do_info()` (implementation-defined text).

- `string change_server(string serveruri) throws ZingolibError`
Updates the lightclient server (empty string switches to default/“offline” URI). Returns `"server set"` or `"Error: ..."`.

---

### Sync / rescan controls

- `string run_sync() throws ZingolibError`
Starts sync if not running, or resumes if paused. Returns status text (or `"Error: ..."`).

- `string poll_sync() throws ZingolibError`
Polls the sync task and returns:

- `"Sync task has not been launched."`, or
- `"Sync task is not complete."`, or
- JSON: `{ "sync_complete": <bool/obj> }` (depending on zingolib result)

- `string pause_sync() throws ZingolibError`
Pauses sync. Returns `"Pausing sync task..."` or `"Error: ..."`.

- `string status_sync() throws ZingolibError`
Returns JSON describing sync status from `pepper_sync::sync_status(...)`.

- `string run_rescan() throws ZingolibError`
Triggers a rescan. Returns `"Launching rescan..."` or `"Error: ..."`.

---

### Keys / identity / parsing utilities

- `string get_seed() throws ZingolibError`
Returns **recovery info JSON** (mnemonic-based), or `"Error: ... no mnemonic found ..."` for key-only wallets.

- `string get_ufvk() throws ZingolibError`
Returns JSON: `{ "ufvk": "<encoded>", "birthday": <u32> }` for account 0.

- `string wallet_kind() throws ZingolibError`
Returns JSON describing how the wallet was loaded and which pools are available (seed/spend/view/empty + booleans).

- `string parse_address(string address) throws ZingolibError`
Parses an encoded address across main/test/regtest and returns JSON including:

- `status`, `chain_name`, `address_kind`
- For unified addresses, also `receivers_available` (+ `only_orchard_ua` when orchard present)

- `string parse_ufvk(string ufvk) throws ZingolibError`
Parses a UFVK and returns JSON including `chain_name`, `pools_available`, etc., or invalid status.

- `string check_my_address(string address) throws ZingolibError`
Checks whether `address` is derived from wallet keys. Returns JSON with `is_wallet_address` plus detailed metadata (type, indices, encoded address, etc.).

---

### Addresses

- `string get_unified_addresses() throws ZingolibError`
Returns JSON list/details of wallet unified addresses.

- `string get_transparent_addresses() throws ZingolibError`
Returns JSON list/details of wallet transparent addresses.

- `string create_new_unified_address(string receivers) throws ZingolibError`
Generates a new unified address for account 0. `receivers` controls pools by containing:

- `'o'` => orchard
- `'z'` => sapling
Returns JSON with account, address index, flags, and encoded UA.

- `string create_new_transparent_address() throws ZingolibError`
Generates a new transparent address for account 0. Returns JSON with account, index, scope, and encoded address.

---

### Wallet data queries

- `string get_balance() throws ZingolibError`
Returns JSON account balance for account 0.

- `string get_value_transfers() throws ZingolibError`
Returns JSON of wallet value transfers (history/tx-related summary).

- `string get_messages(string address) throws ZingolibError`
Returns JSON of messages containing the given address (notes/memos/messages view, implementation-defined).

- `string get_total_memobytes_to_address() throws ZingolibError`
Returns JSON aggregate “memo bytes to address”.

- `string get_total_value_to_address() throws ZingolibError`
Returns JSON aggregate “value received to address”.

- `string get_total_spends_to_address() throws ZingolibError`
Returns JSON aggregate “spends to address”.

- `string get_spendable_balance_total() throws ZingolibError`
Returns JSON: `{ "spendable_balance": <u64> }` computed from shielded spendable balance.

- `string get_spendable_balance_with_address(string address, string zennies) throws ZingolibError`
**Deprecated / “we don’t use this anymore”**. Computes max send value to a specific address (parses `zennies` bool-like string). Returns JSON or error string.

---

### Transaction lifecycle

- `string send(string send_json) throws ZingolibError`
**Propose-send step.** Takes a JSON array of recipients like:

- `address` (string)
- `amount` (u64 zatoshis)
- optional `memo` (string; `"0x..."` treated as hex if decodable)
Returns JSON containing either `{ "fee": <u64> }` or `{ "error": "..." }`. (Does **not** broadcast.)

- `string confirm() throws ZingolibError`
**Broadcast step.** Sends the stored proposal and returns JSON `{ "txids": [ "...", ... ] }` or `{ "error": "..." }`.

- `string shield() throws ZingolibError`
**Propose shielding.** Returns JSON with `{ "value_to_shield": <u64>, "fee": <u64> }` or `{ "error": "..." }`. (Broadcast happens via `confirm()`.)

- `string resend_transaction(string txid) throws ZingolibError`
Attempts to resend a tx by hex txid. Returns success/error string.

- `string remove_transaction(string txid) throws ZingolibError`
Removes an unconfirmed tx from the wallet by txid. Returns success/error string.

---

### Tor + price

- `string create_tor_client(string datadir) throws ZingolibError`
Creates a Tor client (if not already present). Returns success/error string.

- `string remove_tor_client() throws ZingolibError`
Removes Tor client (if present). Returns success/error string.

- `string zec_price(string tor) throws ZingolibError`
Updates and returns the current ZEC price. `tor` is parsed as bool-like string; if true, requires an existing Tor client. Returns JSON `{ "current_price": ... }` or `"Error: ..."`.

---

### Other

- `string get_version() throws ZingolibError`
Returns zingolib git description string.

- `string get_developer_donation_address() throws ZingolibError`
Returns the developer donation address string constant.

- `string get_zennies_for_zingo_donation_address() throws ZingolibError`
Returns the “Zennies for Zingo” donation address string constant.

- `string set_config_wallet_to_test() throws ZingolibError`
Sets wallet settings to “test” defaults (min confirmations = 1, performance = Medium) and marks `save_required = true`. Returns status string.

- `string set_config_wallet_to_prod(string performancelevel, u32 minconfirmations) throws ZingolibError`
Sets wallet performance + min confirmations and marks `save_required = true`. Returns status string or error.

- `string get_config_wallet_performance() throws ZingolibError`
Returns JSON `{ "performance_level": "Low|Medium|High|Maximum" }`.

- `string set_option_wallet() throws ZingolibError`
Currently unimplemented: always returns `"Error: unimplemented"`.

- `string get_option_wallet() throws ZingolibError`
Currently unimplemented: always returns `"Error: unimplemented"`.