libvpack-rs: Independent VTXO Verification

A pure-Rust, no_std clean-room engine for auditing, visualizing, and independently recovering Ark Layer 2 VTXOs.

⚠️ CURRENT LIMITATION (See Phase 7): libvpack-rs currently verifies Path Existence (that an exit path is structurally valid and signatures match) but does not yet verify Path Exclusivity (full Taproot tree reconstruction to prove the non-existence of alternative ASP spend paths). This is our current Priority 0.

The VTXO: The Fundamental Unit of Layer 2 Scaling

As Bitcoin Layer 2 protocols evolve, the Virtual UTXO (VTXO) has emerged as a shared technical primitive. While protocols are exploring different throughput optimizations, a user's proof-of-ownership is ultimately an off-chain VTXO residing within a pre-signed transaction tree.

The Need for Independent Verification

As the Ark ecosystem matures, implementations like Arkade (by Ark Labs) and Bark (by Second) are naturally diverging into specific technical "dialects" optimized for different use cases. While this rapid innovation is incredibly healthy for Bitcoin, it introduces several challenges for the broader ecosystem:

1. Implementation-Coupled Verification: Currently, core teams build both the ASP server and the client SDKs used to verify its operations. In complex cryptographic systems, shared assumptions between a server and its companion SDK can sometimes obscure edge cases. The ecosystem benefits heavily from an independent, "clean-room" verifier to provide thorough, external review of VTXO exits.
2. Vendor-Locked Recovery: True self-sovereignty requires that a user can reclaim their base-chain Bitcoin without relying on the specific company that issued their L2 balance. Currently, users rely heavily on provider-specific SDKs to unilaterally exit.
3. The Hardware Bottleneck: Feature-rich client SDKs are excellent for hot wallets, but they inherently carry larger dependency footprints. For highly constrained, high-security environments like no_std hardware wallets, importing a full protocol stack just to verify an exit path is prohibitive.
4. Covenant Complexity: Ark's underlying covenant math is brilliantly designed but highly complex. Even though the protocols are open-source, the raw Taproot tree structures can be difficult for newcomers to visualize and fully grasp without dedicated educational tools.

The Solution: V-PACK

libvpack-rs implements the V-PACK standard: a neutral, implementation-agnostic verification engine. It acts as the ecosystem's independent auditor, sovereign life raft, and educational bridge.

Core Pillars

• Independent Security Audit [In Progress]: Moving towards a clean-room implementation of BIP-341 Taproot reconstruction. The goal is to independently verify "Path Exclusivity"—mathematically proving the strict absence of ASP backdoors. (Note: libvpack-rs currently verifies structural existence; strict exclusivity auditing is the immediate next phase).
• Sovereign Recovery ("The Fire Escape") [Planned]: Building third-party tooling to let users view, understand, and directly broadcast their fully-signed L1 exit transactions independently of the provider-specific software stack that issued the VTXO.
• Hardware-Native (no_std) Baseline [Current]: A zero-dependency core logic designed strictly for resource-constrained devices, establishing the foundational open-source plumbing that hardware wallets can eventually use to verify Ark natively without vendor lock-in.
• Transparency & Education [Current & Expanding]: Powers local WASM visualizers (like vtxopack.org) that break open the "black box" of covenant math. Upcoming phases will graphically map the full Taproot tree and script execution logic.

---

Bridging the Dialect Gap

Arkade and Bark utilize distinct mathematical identities and sequencing logic for the same Bitcoin primitives. libvpack-rs bridges this gap at the data layer to provide a unified verification standard:

Implementation	ID Format	Logic	Byte Size	nSequence Signal
Arkade (Ark Labs)	Transaction-Native	sha256d(Bitcoin_V3_Tx)	32 Bytes	0xFFFFFFFE (TRUC RBF)
Bark (Second)	Object-Native	sha256d(Tx):Index	36 Bytes	0x00000000 (BIP-68 Timelocks)

---

Quick Start (Rust)

Add vpack to your Cargo.toml:

vpack = { version = "1.0.0-rc.2", default-features = false }

1. Independently Audit a VTXO

use vpack::{verify, VtxoId};

// Raw bytes from an ASP, a V-PACK file, or local state
let raw_vpack: &[u8] = get_bytes_from_backup(); 
let expected_id = VtxoId::from_str("47ea55bc...:0").unwrap();

// Clean-room verification: mathematically reconstructs the path to the L1 anchor
match vpack::verify(raw_vpack, &expected_id) {
    Ok(tree) => println!("VTXO Verified! Independent Audit Passed. Amount: {:?}", tree.leaf.amount),
    Err(e) => eprintln!("Audit Failed - Invalid State: {:?}", e),
}

2. Universal Export (Standardization)

use vpack::export::{create_vpack_ark_labs, ArkLabsIngredients};

// Take raw ingredients (Amounts, Scripts, Sequences) from a specific 
// implementation and serialize them into the lightweight V-PACK standard.
let ingredients = ArkLabsIngredients { /* ... */ };
let universal_vpack = create_vpack_ark_labs(ingredients)?;

---

WASM Support & "The Glass VTXO"

The wasm-vpack workspace crate provides headless verification with auto-inference for web browsers. This enables transparent educational tools.

cd wasm-vpack && wasm-pack build --target web

See vtxopack.org for a live implementation of the VTXO-Inspector.

---

Project Roadmap

• Phase 1-5: Forensic Audit & Core Logic. Byte-level reconciliation of nSequence, Fee Anchors, and Identity Models across divergent Ark implementations.
• Phase 6: The VTXO-Inspector. A WASM-powered visualizer at vtxopack.org, enabling users to parse and verify L2 balances locally in the browser.
• Phase 7 (CURRENT PRIORITY): Path Exclusivity Engine (Security & Cryptographic Audit). Implementing pure-Rust BIP-341 Taproot reconstruction. Building the engine to audit the entire VTXO Taptree, mathematically proving the strict non-existence of ASP backdoors or hidden sweep scripts.
• Phase 8: "The Glass VTXO" (Transparency & Education). Upgrading the visualizer to parse and graphically display the full Taproot tree and underlying Bitcoin scripts, creating an interactive UX where developers can visually learn how Ark covenants execute.
• Phase 9: "The Sentinel" (Automated Drift Detection & Code Review). Implementing daily automated CI monitoring against upstream Arkade and Bark codebases to catch silent covenant changes, alerting the community and acting as an automated early-warning system.
• Phase 10: "The Fire Escape" (Sovereign Recovery Generation). Transitioning the library from verifying state to trustlessly generating fully-signed L1 exit transactions, complete with fee-rate awareness, allowing users to broadcast their sovereign exit independently of the provider-specific software stack.
• Phase 11: Standardized Specifications & Educational Deep-Dives. Writing the formal V-PACK open-source specification and publishing technical deep-dives to educate newcomers on L2 Taproot engineering.