Keystone

Bitcoin-native settlement infrastructure for intent systems, solvers, wallets, and cross-chain protocols.

Keystone lets protocols settle native BTC payments without custody, without wrapped BTC, without a committee, and without a permanent relay.

The BTC moves directly on Bitcoin.
What crosses systems is proof, not an asset.

Keystone is designed for teams that need Bitcoin settlement in an intent, solver, DeFi, wallet, or cross-chain flow, but do not want to custody BTC or depend on wrapped representations.

---

Try it now

Clone the repository and run the local demo:

git clone https://github.com/keystone-settlement/keystone
cd keystone
./keystone.sh

The demo runs a deterministic local Bitcoin regtest and a real local EVM through Anvil.

It demonstrates:

• a solver opening an order;
• a user paying native BTC;
• an honest claim settling successfully;
• a fraudulent claim being challenged and defeated;
• an unpaid order being refunded;
• an insufficient payment being rejected;
• a late payment being rejected;
• artifacts written locally for inspection.

Prerequisites:

• Rust stable, via rustup;
• Foundry, via foundryup;
• Linux/macOS environment.

The demo does not require a GPU, special hardware, or a running Bitcoin node. The local harness starts what it needs.

---

Who Keystone is for

Keystone is for teams building:

• intent protocols that need native BTC settlement;
• solver networks that want to support BTC without custody;
• Bitcoin DeFi products;
• wallets or infrastructure products that need auditable Taproot-based settlement;
• cross-chain protocols that want to reduce bridge and wrapped-asset risk;
• security teams evaluating alternatives to custodial bridges;
• researchers working on Bitcoin light clients, proof-based settlement, PTLCs, DLCs, or atomic coordination.

If your product needs “BTC on the other side” but does not want to custody BTC or mint wrapped BTC, Keystone is the type of primitive you should evaluate.

---

The problem

Most cross-chain BTC flows rely on one of the following:

• a custodian;
• a committee;
• a wrapped representation;
• a bridge;
• a trusted attestation layer;
• or a relay that users must trust operationally.

Keystone takes a different route.

The destination system does not receive BTC.
It verifies that a native Bitcoin payment happened.

That distinction matters.

The Bitcoin payment remains a real Bitcoin transaction. The destination system only acts after a proof package, challenge, or succinct proof validates the settlement condition.

---

What Keystone does

Keystone is a Bitcoin settlement module for systems that need to coordinate value across environments.

At a high level:

Solver locks value on an EVM chain
        ↓
User pays native BTC
        ↓
A proof package is produced
        ↓
The settlement contract accepts a valid claim
        ↓
Invalid claims can be challenged
        ↓
The honest party settles

In v1.1, Keystone is optimistic:

• claims are posted with a bond;
• invalid claims can be challenged with a concrete fraud proof;
• the challenge window protects the system;
• a successful challenge slashes the fraudulent claim bond;
• valid claims settle after the challenge window.

The v2 path replaces the challenge window with a succinct proof of Bitcoin verification.

---

What the current demo proves

The local demo runs five scenarios:

1. Happy path
   A valid native BTC payment is detected, claimed, and settled.

2. Fraudulent claim defeated
   A claim with a concrete defect is challenged and defeated on-chain.

3. Unpaid expiry
   No valid BTC payment arrives before the deadline, so the locked asset is refunded.

4. Insufficient payment
   A real BTC payment below the required amount is rejected.

5. Late payment
   A real payment whose block timestamp exceeds the payment deadline is rejected.

The expected result is not just “tests pass.” Keystone produces local artifacts that can be inspected.

---

Proof it works

The repository includes:

• a Rust reference verifier;
• Solidity settlement contracts;
• differential tests between the Rust verifier and Solidity;
• a full local end-to-end harness;
• real Bitcoin regtest execution;
• Foundry contract tests;
• fuzzing of parsers and malformed inputs;
• a measured succinct-proof path.

At the last recorded run:

120 Rust tests
100 Foundry tests
fuzz + solvency invariant
clippy-clean
5-scenario local E2E harness green on Anvil

The ZK gate has also been measured:

• SP1 core proof over the unmodified reference verifier;
• compressed proof;
• Groth16 wrap;
• on-chain verification in a Forge test;
• 225,820 gas for the real proof verifier path;
• 356 bytes of calldata for the Groth16 proof.

---

What is on-chain today

The Rust verifier is the source of truth.

The Solidity contracts implement the high-value fraud proofs that mirror the Rust rules.

Rule	Reference verifier	Solidity
Header proof-of-work	✅	✅
Header linkage	✅	✅
Difficulty / nBits	✅	✅
Confirmation depth	✅	✅
Merkle inclusion	✅	✅
Transaction canonicity	✅	✅
Payment amount + address	✅	✅
Median-time-past	✅	✅
Payment deadline	✅	✅
Header-chain extension	✅	✅
P2TR/BIP86 address binding	✅	Reference-side in Phase A

The full mainnet 2016-block retarget is verified on-chain and tested differentially against the reference on real mainnet headers crossing the height-2016 boundary.

---

Trust model

Keystone v1.1 is trust-minimized, not trustless.

It depends on:

1. An honest checkpoint
   The checkpoint root is governed by CheckpointRegistry. Anyone may extend a checkpoint permissionlessly through extendCheckpoint, with consensus checks verified on-chain.

2. L2 liveness
   A challenge transaction must be able to land within the challenge window.

3. At least one honest challenger
   Fraudulent claims are defeated by challengers during the window.

The phrase “no custody, no committee” applies to the Keystone design.

The word “trustless” is reserved for the v2 path, where a succinct proof replaces the optimistic challenge window.

---

ZK gate: measured, not guessed

Before claiming a trustless v2 path, Keystone measured the proof cost.

The unmodified Rust reference verifier runs as an SP1 zkVM guest over the valid differential vector:

• header chain verification;
• proof-of-work;
• difficulty;
• median-time-past;
• Merkle inclusion;
• payment amount/address;
• deadline;
• public output equal to the canonical claim digest.

Measured campaign results on CPU:

Stage	Time	Peak RSS	Artifact
Core proof	37.2s median	10.5 GiB	2,781,255 B
Compressed proof	118.6s median	18.4 GiB	1,272,601 B
Groth16 wrap	~16.2 min	18.5 GiB	356 B calldata
On-chain verification	—	—	225,820 gas

The ZK gate is not a promise. It is measured evidence.

See:

• docs/zk-spike-report.md
• docs/OPT_FEASIBILITY_REPORT.md
• spike/zk/

---

Repository layout

crates/
  verifier/   Reference verifier: hashes, U256 difficulty math, header chain,
              proof-of-work, retarget, MTP, Merkle, transaction parsing,
              proof package, fraud model, deterministic regtest builder.

  btc/        Bitcoin RPC client, block tooling, btcmock, claimerd.

  evm/        Minimal EVM JSON-RPC / ABI / RLP transport.

  watcher/    Payment scanner and honest challenger.

  solver/     Order construction and unique-address-per-order invariant.

  harness/    End-to-end driver: Anvil + contracts + reference agents.

contracts/
  src/        BtcProofLib, CheckpointRegistry, Settler.

  test/       Differential, state-machine, and end-to-end scenario tests.

spike/zk/     SP1 guest/host, gas measurement, proof campaign evidence.

---

Build and test

Run Rust tests:

cargo test --workspace

Regenerate differential vectors:

cargo run -p keystone-verifier --example gen_vectors

Run Solidity tests:

cd contracts
forge test

Run the local end-to-end demo:

./keystone.sh e2e

Run the default guided demo:

./keystone.sh

---

Commercial pilots and integrations

Keystone is source-available under the Business Source License 1.1.

Development, testing, academic research, security review, and public-testnet deployment are free under the Additional Use Grant.

Production use with real value at risk requires a commercial agreement during the BUSL window.

We are currently looking for a small number of technical pilot partners.

Keystone may be relevant if you are building:

• an intent protocol that needs native Bitcoin settlement;
• a solver network that wants to support BTC without custody;
• a Bitcoin DeFi product;
• a cross-chain protocol that wants to avoid wrapped BTC;
• a wallet or infrastructure product that needs auditable Bitcoin settlement;
• a security or research team evaluating bridge alternatives.

Possible engagement formats:

• signet/testnet pilot;
• integration support;
• custom watcher or solver adaptation;
• verifier integration;
• protocol architecture review;
• commercial production license.

For pilot discussions, include:

• your protocol or use case;
• target chain or L2;
• expected settlement flow;
• whether you need testnet support, integration support, or production licensing.

---

What Keystone is not

Keystone is not:

• a wrapped BTC bridge;
• a custodial bridge;
• a committee-based bridge;
• a relayer you must trust;
• a promise of mainnet readiness today;
• a replacement for external audit;
• a token launch.

Keystone is settlement infrastructure.

The repository demonstrates the first real slice: a working local protocol, on-chain fraud proofs, reference verification, and a measured ZK path.

---

Roadmap

v1.1 — optimistic settlement

Current path:

• unique Bitcoin address per order;
• proof package;
• bonded claims;
• challenge window;
• fraud proofs;
• challenge slashing;
• settlement after challenge window.

v2 — succinct proof settlement

The succinct proof replaces the challenge window.

The contract already includes finalizeWithProof, and a real proof verifies on-chain in a Forge test at 225,820 gas.

Remaining work:

• verifier adapter;
• production prover pipeline;
• batch aggregation;
• recursive checkpointing;
• production parameter calibration;
• external audit.

Reverse orders

User locks an EVM asset, solver pays native BTC, and redeems with payment proof.

Mode S

Atomic swap with a counterparty using adaptor signatures over Taproot.

Other UTXO chains

The verifier architecture can generalize to other UTXO-family chains. ZK-hostile proof-of-work systems are deferred.

---

What “finished” means

Keystone is not production-ready until:

• production parameters are calibrated from testnet data;
• a production watcher and solver are deployed;
• proof parameters and limits are frozen;
• an external cryptographer audits the system;
• challenge economics are tested;
• operational runbooks exist;
• testnet deployments have produced public artifacts;
• value caps and emergency procedures are defined.

The repository reaches the end of the first real slice.

The next slice is public testnet evidence.

---

License

Keystone is licensed under the Business Source License 1.1.

It converts automatically to MIT on 2028-07-02.

Allowed under the Additional Use Grant:

• development;
• testing;
• academic research;
• security review;
• public-testnet deployment.

Production use with real value at risk requires a commercial agreement during the BUSL window.

Vendored third-party code under spike/zk/gas/src/ retains its original MIT license.

See LICENSE.

---

Contact

Leonardo Victor Ribeiro
GitHub: @keystone-settlement

For pilots, integrations, research feedback, or commercial licensing, open an issue or contact the maintainer.

Useful context to include:

• your protocol or product;
• whether you are a solver, wallet, intent protocol, auditor, or researcher;
• target chain/L2;
• whether you want a signet/testnet pilot, integration support, or production licensing.

If any claim in this README looks wrong, open an issue. Technical corrections are welcome.

SPDX-License-Identifier: BUSL-1.1