bark-wallet

name	bark-wallet
description	Self-custodial Bitcoin wallet on the Ark protocol (Bark implementation) with Lightning support
model-invocation	autonomous
trigger	["bark","ark wallet","ark payment","bitcoin L2","vtxo","lightning payment","bolt11","send bitcoin","receive bitcoin"]
env	[{"name":"BARK_MNEMONIC","description":"BIP39 mnemonic seed phrase (12 or 24 words) for wallet access","required":true},{"name":"BARK_SERVER_URL","description":"Ark server URL","required":false,"default":"https://ark.signet.2nd.dev"},{"name":"BARK_ESPLORA_URL","description":"Esplora block explorer URL for chain data","required":false,"default":"https://esplora.signet.2nd.dev"},{"name":"BARK_DATADIR","description":"Directory for wallet database and state","required":false,"default":"./bark-data"}]

Bark Wallet Skill

A self-custodial Bitcoin wallet skill using Bark (Rust implementation of the Ark protocol by Second). Enables autonomous agent transactions on Ark L2 and Lightning Network.

Architecture Overview

What is Ark?

Ark is a Bitcoin Layer 2 protocol that uses Virtual Transaction Outputs (VTXOs) — off-chain, pre-signed transactions that users can broadcast at any time to recover funds on-chain. An Ark server coordinates periodic "rounds" to refresh VTXOs and manage liquidity.

Trust Model

• The Ark server can censor (refuse to process) but cannot steal funds
• Emergency exit: users can always broadcast pre-signed transactions to recover bitcoin on-chain without server cooperation
• Out-of-round (arkoor) payments require trusting that sender and server don't collude until next refresh
• Refreshing VTXOs upgrades security from spend VTXOs to refresh VTXOs

VTXO Lifecycle

• VTXOs expire after ~30 days (configurable per server)
• Must be refreshed or spent before expiry, otherwise the server can claim them
• Refresh happens during server rounds (~30 seconds on signet)
• Wallet should auto-refresh VTXOs approaching expiry

Fee Structure (Second's signet server)

Operation	Fee
Ark send (L2-to-L2)	0%
Ark receive	Free
Lightning send	0.2–0.5% (10 sat min)
Lightning receive	Free
On-chain send	0.2–0.5% + on-chain fees
VTXO refresh	0–0.5% (free if <2 days to expiry)

Fees are server policy, not protocol-enforced. Different servers may charge differently.

Lightning Integration

Lightning is native via the Ark server — no swap services needed. The server acts as a Lightning gateway, handling channel management, routing, and liquidity.

Setup Requirements

1. Rust toolchain: Install via https://rustup.rs
2. System dependencies: build-essential, clang, protobuf-compiler (Linux)
3. Build the agent: cargo build --release
4. Set environment: Export BARK_MNEMONIC with a BIP39 seed phrase

Generate a new mnemonic for testing:

cargo run --example wallet_setup

Agent API Reference

The BarkAgent struct wraps the bark-wallet crate into a high-level interface.

BarkAgent::create(mnemonic, options) -> Result<BarkAgent>

Factory constructor. Initializes wallet from mnemonic and connects to Ark server.

Parameters:

• mnemonic: &str — BIP39 seed phrase (12 or 24 words)
• options: BarkAgentOptions — Server URL, esplora URL, data directory (always signet)

Example:

let agent = BarkAgent::create("abandon abandon ... about", BarkAgentOptions::default()).await?;

---

agent.get_identity() -> Result<Identity>

Returns the wallet's Ark address.

Returns: Identity { address: String }

---

agent.get_balance() -> Result<Balance>

Returns current wallet balance across all categories. Automatically syncs before returning.

Returns:

Balance {
    spendable_sat: u64,           // Immediately spendable
    pending_lightning_send_sat: u64,
    claimable_lightning_receive_sat: u64,
    pending_in_round_sat: u64,
    pending_board_sat: u64,
    pending_exit_sat: Option<u64>,
}

---

agent.get_ark_address() -> Result<String>

Generates the next unused Ark receiving address from the HD keychain.

---

agent.send_ark_payment(destination, amount_sat) -> Result<String>

Sends an Ark (L2-to-L2) payment to an Ark address.

Parameters:

• destination: &str — Ark address
• amount_sat: u64 — Amount in satoshis

Example:

agent.send_ark_payment("ark1q...", 1000).await?;

---

agent.create_lightning_invoice(amount_sat) -> Result<String>

Creates a BOLT11 invoice to receive a Lightning payment.

Parameters:

• amount_sat: u64 — Amount in satoshis

Returns: BOLT11 invoice string

---

agent.pay_lightning_invoice(invoice, amount_sat) -> Result<String>

Pays a BOLT11 Lightning invoice.

Parameters:

• invoice: &str — BOLT11 invoice string
• amount_sat: Option<u64> — Optional amount override (for amountless invoices)

Returns: Success message

---

agent.get_history() -> Result<Vec<Movement>>

Returns full transaction history, newest first.

Returns: Vector of Movement structs with:

• id, status (pending/successful/failed/canceled)
• effective_balance_sat, offchain_fee_sat
• sent_to, received_on destinations
• created_at, completed_at timestamps

---

agent.list_vtxos() -> Result<Vec<VtxoInfo>>

Lists spendable wallet VTXOs with state and expiry information.

Returns: Vector of VtxoInfo with: id, amount_sat, expiry_height, state

---

agent.list_all_vtxos() -> Result<Vec<VtxoInfo>>

Lists all wallet VTXOs including spent ones.

---

agent.refresh_vtxos() -> Result<()>

Refreshes VTXOs that are approaching expiry. Extends their lifetime by participating in the next Ark round.

---

agent.offboard_all(address) -> Result<String>

Cooperatively moves all VTXOs off Ark to an on-chain address.

Parameters:

• address: &str — On-chain Bitcoin destination address

---

agent.send_onchain(address, amount_sat) -> Result<String>

Sends a specific amount to an on-chain address from Ark balance.

Parameters:

• address: &str — On-chain Bitcoin destination address
• amount_sat: u64 — Amount in satoshis

---

agent.sync()

Forces immediate wallet sync: updates fee rates, processes incoming payments, resolves pending Lightning.

---

agent.maintenance() -> Result<()>

Runs full maintenance: sync + refresh VTXOs approaching expiry.

---

agent.is_connected() -> bool

Checks if the wallet has an active connection to the Ark server.

---

agent.cleanup() -> Result<()>

Graceful shutdown. Drops wallet connection.

Error Handling

Error	Cause	Recovery
InsufficientBalance	Not enough spendable sats	Check balance, wait for pending to confirm
VtxoExpired	VTXO passed expiry height	Cannot recover — funds forfeited to server
ServerUnreachable	Cannot connect to Ark server	Retry, or emergency exit if prolonged
RoundTimeout	Refresh round didn't complete	Retry on next round
InvalidDestination	Unrecognized address format	Verify destination string
LightningPaymentFailed	Route not found or invoice expired	Check invoice, retry with different route

Security Rules

• NEVER log, print, or expose the mnemonic
• NEVER commit .env files or mnemonics to version control
• ALWAYS keep minimal balances in agent wallets
• ALWAYS use separate mnemonics per agent
• ALWAYS refresh VTXOs before expiry (automate this)
• Agent wallets should be treated as hot wallets — sweep to cold storage regularly

Network Configuration

This skill is hardcoded to signet only. Mainnet is not supported.

Ark Server	Esplora	Faucet
https://ark.signet.2nd.dev	https://esplora.signet.2nd.dev	https://signet.2nd.dev