> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yattacorp.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# NEXUS-Bitcoin

> Smart contracts on Bitcoin — how it works and what you can do

<Warning>
  **NEXUS-Bitcoin launches after Zcash.** Zcash is the first live chain. Bitcoin support is fully designed and implemented — this page documents what Bitcoin integration will look like at launch.
</Warning>

## Overview

NEXUS-Bitcoin brings smart contracts to Bitcoin without changing Bitcoin itself. Your BTC stays in a Bitcoin vault. NEXUS runs programs on top.

**What NEXUS adds to Bitcoin:**

* Smart contracts (written in Rust/WASM)
* Fungible tokens (NEP-20)
* Decentralized trading (AMM pools)
* BRC-20 token bridging

<Tip>
  New to NEXUS? Start with the [Introduction](/introduction) for plain-English context. See the [Glossary](/glossary) for any unfamiliar terms.
</Tip>

***

## How Trust Works on Bitcoin

NEXUS-Bitcoin is trustless — you don't need to trust any individual operator. Here's how:

**Step 1 — Cryptographic proofs**

Every time NEXUS processes a batch of transactions, it generates a [ZK-STARK proof](/glossary#z) — a mathematical certificate proving all transactions were handled correctly.

**Step 2 — Anyone can challenge**

Proofs are posted to Bitcoin along with a financial bond (deposited by the operator). If the proof is wrong, anyone in the world can challenge it using [BitVM2](/glossary#b):

```
1. Challenger posts a bond and opens a dispute
2. A bisection game narrows to the single bad computation step
3. That step is verified on Bitcoin itself
4. Wrong party loses their bond to the correct party
```

No permission needed. No special access. Anyone can be a challenger.

**Step 3 — Your escape hatch**

Even without any challenge process, you always hold a pre-signed exit transaction. If NEXUS stops working, wait \~2 weeks and your BTC returns to you automatically.

***

## Bitcoin Vault Details

| Property              | Value                                                           |
| --------------------- | --------------------------------------------------------------- |
| Address type          | [Taproot (P2TR)](/glossary#t) — Bitcoin's modern address format |
| Vault structure       | 2-of-2 multisig (you + protocol)                                |
| Escape hatch          | 2,016 block timelock (\~2 weeks)                                |
| State commitments     | [OP\_RETURN](/glossary#o) outputs every N blocks                |
| Deposit confirmations | 6 blocks (\~60 min)                                             |

***

## Supported Features (V1)

| Feature                      | Status                  |
| ---------------------------- | ----------------------- |
| Smart Contracts (WASM)       | ✅                       |
| Taproot Vaults               | ✅                       |
| State Commitments on Bitcoin | ✅                       |
| BitVM2 Fraud Proof System    | ✅                       |
| SPV Transaction Proofs       | ✅                       |
| Cross-Contract Calls         | ✅                       |
| BRC-20 Token Bridge          | ✅                       |
| BTC ↔ ZEC Swaps              | 🔄 V2 (intent exchange) |
| BTC ↔ DOGE Swaps             | 🔄 V2 (intent exchange) |
| Unified Liquidity Pools      | 🔄 V2                   |
| Runes Bridge                 | 🔄 Coming soon          |
| Ordinals                     | 🔄 Coming soon          |

***

## Smart Contract Capabilities

NEXUS-Bitcoin supports the full WASM smart contract system:

| Capability                        | Description                                         |
| --------------------------------- | --------------------------------------------------- |
| Full WASM execution               | Any logic expressible in Rust                       |
| Cross-contract calls              | One contract calling another                        |
| Delegate calls                    | Run another contract's code in your storage context |
| Contract-from-contract deployment | Factory patterns                                    |
| Persistent storage                | Key-value data that survives between calls          |
| Event emission                    | Notify off-chain indexers                           |
| Reentrancy guard                  | Built-in protection against reentrancy attacks      |
| Bitcoin SPV proofs                | Verify Bitcoin transactions inside a contract       |

***

## Deposit Guide

**1. Get your vault address**

```typescript theme={null}
const vault = await client.getVaultAddress(2016); // 2,016-block timelock (~2 weeks)
console.log('Send BTC to:', vault.vaultAddress);
```

Or via CLI:

```bash theme={null}
nexus wallet vault-address --chain bitcoin
```

**2. Send Bitcoin**

```bash theme={null}
bitcoin-cli sendtoaddress <VAULT_ADDRESS> 0.01
```

**3. Wait for 6 confirmations** (\~60 minutes)

**4. Check your NEXUS balance**

```typescript theme={null}
const balance = await client.getBalance();
// Balance shown in satoshis (vSAT)
```

***

## Withdrawal Guide

```typescript theme={null}
// Returns: { success, txid, status, path, confirmed? }
const result = await client.withdrawFunds(
  'bc1p...',  // your Bitcoin destination address
  100000,     // amount in satoshis
);
console.log('Withdrawal txid:', result.txid);
```

Withdrawals are processed in batches for efficiency. You receive BTC in your Bitcoin wallet within a few minutes of processing.

***

## State Commitments

NEXUS posts a summary of all state changes to Bitcoin periodically:

```
Bitcoin Block 100:  State Root 0xabc... (stored in OP_RETURN)
Bitcoin Block 200:  State Root 0xdef... (stored in OP_RETURN)
Bitcoin Block 300:  State Root 0x123... (stored in OP_RETURN)
```

Anyone can verify NEXUS is behaving correctly by:

1. Downloading the full NEXUS state from any node
2. Computing the [Merkle root](/glossary#m) of that state
3. Comparing it to the value posted on Bitcoin

***

## Configuration Reference

```toml theme={null}
[bitcoin]
rpc_url = "http://localhost:8332"
rpc_user = "user"
rpc_password = "password"
network = "regtest"  # mainnet | testnet | signet | regtest

[bitcoin.vault]
escape_timelock = 2016  # ~2 weeks in blocks

[bitcoin.state_commit]
interval_blocks = 100   # post state every 100 Bitcoin blocks
bond_amount_sats = 100000
```

***

## Comparison with Bitcoin Alternatives

| Feature         | NEXUS-Bitcoin         | Spark (Lightning) | OP\_NET    | Arch Network |
| --------------- | --------------------- | ----------------- | ---------- | ------------ |
| Smart Contracts | ✅ Full WASM           | ❌ Payments only   | ✅ WASM     | ✅ WASM       |
| Trust Model     | Trustless (ZK+BitVM2) | Federated         | Optimistic | BitVM        |
| Multi-Chain     | ✅ BTC+ZEC+DOGE        | ❌ BTC only        | ❌ BTC only | ❌ BTC only   |
| Self-Custody    | ✅ Always              | ✅ Channels        | Partial    | Bridge-based |
| DeFi            | ✅ AMM, tokens, etc    | ❌                 | ✅          | ✅            |

## Roadmap

### V1 (Live)

* ✅ Full WASM smart contracts
* ✅ Cross-contract calls & delegate calls
* ✅ Taproot vaults with escape hatch
* ✅ ZK-STARK + BitVM2 verification
* ✅ BRC-20 bridge
* ✅ Stealth addresses & encrypted mempool (via NEXUS protocol layer)

### V2 (Planned)

* 🔄 Unified liquidity with ZEC/DOGE via intent exchange
* 🔄 Cross-chain swaps (BTC/ZEC/DOGE)
* 🔄 Runes bridge
* 🔄 Ordinals support