zinc-core

zinc-core is a Rust wallet engine for Bitcoin + Ordinals use cases.

Key capabilities:

deterministic account/key derivation on top of BDK,
taproot-first public API naming,
transaction creation/signing/broadcast helpers,
Ordinal Shield PSBT analysis (burn/movement risk detection),
optional WASM bindings for browser and extension hosts.

Installation

[dependencies]
zinc-core = "0.1"

What You Get

BIP-39 mnemonic generation, validation, and seed derivation
Explicit-network wallet constructors (from_mnemonic, from_seed)
Taproot descriptor-based wallet construction
Unified and dual-account address schemes
Native sync with Esplora backends
Ordinals protection + metadata sync and PSBT analysis
Typed core request/error surfaces (CreatePsbtRequest, ZincError)
WASM exports for wallet lifecycle and runtime log controls

Quick Start (Native Rust)

use zinc_core::{AddressScheme, Network, WalletBuilder, ZincMnemonic};

fn main() -> Result<(), String> {
    // Example mnemonic for development/testing only.
    let mnemonic = ZincMnemonic::parse(
        "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
    )
    .map_err(|e| e.to_string())?;
    let mut wallet = WalletBuilder::from_mnemonic(Network::Regtest, &mnemonic)
        .with_scheme(AddressScheme::Unified)
        .build()?;

    let taproot = wallet.next_taproot_address()?;
    let payment = wallet.get_payment_address()?; // Unified: same taproot branch family

    println!("taproot: {taproot}");
    println!("payment: {payment}");
    Ok(())
}

Address Model

Canonical public naming uses taproot* fields and methods.
In Unified mode, payment role resolves to the same taproot key/address family.
In Dual mode, payment role uses a distinct SegWit payment branch.

Constructor Model

WalletBuilder::from_mnemonic(network, &mnemonic)
WalletBuilder::from_seed(network, seed64)

Example Programs

Run from the workspace root (wallet/zinc-core):

cargo run -p zinc-core --example wallet_setup
cargo run -p zinc-core --example psbt_sign_audit
ESPLORA_URL=https://mempool.space/api \
  cargo run -p zinc-core --example sync_and_balance

wallet_setup.rs: deterministic setup + account/address inspection
sync_and_balance.rs: online sync flow and balance retrieval
psbt_sign_audit.rs: Ordinal Shield analysis over a sample PSBT

WASM Integration Notes

WASM exports include:

stateless helpers: generate_wallet, validate_mnemonic, derive_address, encrypt_wallet, decrypt_wallet
stateful wallet wrapper: ZincWasmWallet
runtime logging controls: set_log_level, set_logging_enabled, get_log_level

WASM payloads are canonicalized to taproot* keys.

init() installs panic hooks only. Host applications should configure their own log subscriber/sink.

Logging Model

Default runtime level is warn
Runtime levels accepted by WASM API: off|error|warn|info|debug|trace
Identifier-rich diagnostics (for example tx/output identifiers) are intended for debug

Security and Stability

This is security-sensitive software. Review release notes before upgrading.
Avoid logging secret material and mnemonic data.
Reporting process: see SECURITY.md.
Discovery APIs are hardened to avoid exposing raw master private keys.

Development Checks

cargo fmt --all -- --check
cargo clippy -p zinc-core --all-targets --all-features -- -D warnings
cargo test -p zinc-core --locked
cargo doc -p zinc-core --no-deps

License

Licensed under MIT. See LICENSE.

zinc-core 0.1.2