⛓️ ChainVow — 链誓

Make a vow on-chain. Let AI enforce it.
在链上立誓，让 AI 中立执行。

---

🌟 What is ChainVow?

ChainVow (链誓) is a dual-party co-managed fund protocol built on OKX OnchainOS. Two parties lock funds together on-chain under a mutual commitment — neither can withdraw unilaterally. When conditions are met, an AI agent executes the withdrawal route automatically and neutrally.

Use cases:

• 💍 Couples saving together (e.g., "unlock on anniversary")
• 🤝 Business partners sharing project funds
• 🎯 Personal milestone commitments (e.g., "unlock when target is hit")
• ⚖️ Dispute resolution with AI as neutral arbiter

---

✨ Core Features

Feature	Description
🔐 Dual-Sig Lock	Both parties must sign — no unilateral withdrawal
🤖 AI Arbiter	OKX onchainos predict serves as neutral judge
💱 Optimal Exit	DEX aggregation finds best swap route at withdrawal
⛽ Gas Transparency	Pre-estimated gas costs, no hidden fees
📊 Real-time Valuation	Live fund value via OKX market data

---

🏗️ How It Works

ChainVow uses the OKX OnchainOS full stack in a 4-step pipeline:

Party A (0xAAAA...) + Party B (0xBBBB...)
         ↓                    ↓
   [ChainVow Dual-Sig Layer]
         ↓
   [OKX OnchainOS]
    ├── okx-wallet-portfolio  →  Query fund balance
    ├── okx-dex-market        →  Real-time ETH price & valuation
    ├── okx-dex-swap          →  Optimal withdrawal route (quote only)
    └── okx-onchain-gateway   →  Gas estimation (EIP-1559)

Step 1 — Fund Portfolio Query

# Query fund wallet ETH balance via JSON-RPC
curl -X POST "https://eth.llamarpc.com" \
  -d '{"jsonrpc":"2.0","method":"eth_getBalance",
       "params":["0xAAAA...DEMO_WALLET","latest"],"id":1}'

Step 2 — Real-time Market Data

# ETH live price via OKX OnchainOS
onchainos market price 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee --chain ethereum
onchainos token price-info 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee --chain ethereum

Step 3 — Optimal Withdrawal Route (Quote Only — Never Executes Without Dual-Sig)

# Get best DEX route: ETH → USDC
# amount = total fund in wei (1 ETH = 1e18 wei)
onchainos swap quote \
  --from 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee \
  --to   0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --amount 150000000000000000 \
  --chain ethereum

Step 4 — Gas Estimation (EIP-1559)

onchainos gateway gas --chain ethereum

---

📸 Demo Screenshots

Demo Fund: Wallet A (0.1 ETH) + Wallet B (0.05 ETH) = 0.15 ETH

⚠️ All wallet addresses in screenshots are anonymized demo addresses.

---

Step 1 · Fund Portfolio
Result: Party A: 0.100 ETH ($208.36) · Party B: 0.050 ETH ($104.18) · Total: $312.55

---

Step 2 · ETH Real-time Price
Result: ETH $2,083.63 · Fund value $312.55 USD

---

Step 3 · Optimal Swap Route (Quote Only)
Result: 0.15 ETH → 312.598 USDC · Via Uniswap V4 (76%) + Wintermute (30%) · slippage -0.04%

---

Step 4 · Gas Estimation
Result: 1,164,812 Gwei ≈ $2.43 USD · baseFee 28.55 Gwei (EIP-1559)

---

📊 Demo Results

Step	Tool	Result
Fund Query	okx-wallet-portfolio	A: 0.1 ETH + B: 0.05 ETH = 0.15 ETH
Market Price	okx-dex-market	ETH $2,083.63 · Fund $312.55
Swap Quote	okx-dex-swap	0.15 ETH → 312.60 USDC · 4-hop route
Gas Estimate	okx-onchain-gateway	~$2.43 · EIP-1559 baseFee 28.55 Gwei

---

🔐 Security Design

Risk	ChainVow Protection
Single-party rug	✅ Dual-sig required for any withdrawal
Front-running	✅ Quote-only until both parties confirm
Hidden fees	✅ Gas pre-estimated and shown upfront
Unauthorized execution	✅ AI arbiter validates conditions before broadcast

Swap is NEVER executed without dual-signature + AI arbiter confirmation.
onchainos swap quote only fetches routing data — no broadcast, no funds moved.

---

🛠️ Tech Stack

Layer	Technology
On-chain	Ethereum Mainnet (EIP-1559)
DEX Aggregation	OKX OnchainOS (onchainos CLI v0.1.0)
Market Data	OKX DEX Market API
Gas Oracle	OKX OnchainOS Gateway
AI Arbiter	OKX onchainos predict (Coming Soon)
RPC	eth.llamarpc.com (public JSON-RPC)

---

🚀 Quick Start

# Install OKX OnchainOS CLI
# See: https://www.okx.com/web3/onchainos

# Clone this repo
git clone https://github.com/Fishking888/chain-vow.git
cd chain-vow

# Query fund value
onchainos market price 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee --chain ethereum

# Get withdrawal quote (replace with actual fund amount in wei)
onchainos swap quote \
  --from 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee \
  --to   0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --amount YOUR_AMOUNT_IN_WEI \
  --chain ethereum

# Estimate gas
onchainos gateway gas --chain ethereum

---

⚠️ Disclaimer

This project is a technical demonstration for the OKX OnchainOS hackathon. All wallet addresses shown in demos are anonymized examples. No real funds were moved — all swap operations are quote-only. This does not constitute financial advice.

---

📄 License

MIT © 2026 ChainVow

---

Built with ⛓️ by ChainVow · Powered by OKX OnchainOS