快速上手 · Ksana

本页带你从零开始，完成一笔在比特币上已经最终的转账。一切都在公开 signet 上进行，那是 Ksana 运行在比特币 signet 上的测试网络：上面的币没有价值，主网也尚未上线。

两条路线，任选其一。在浏览器中需要一个比特币钱包扩展，花上几分钟。在命令行中需要 Rust 工具链，网络返回的每一个值都看得到。

无论走哪条路线，你的操作都会经过三道印记：

≈ 5 秒 快轨确认 已在快轨上执行：余额已经变动，合约看得到新状态。
下一个比特币区块 已写入比特币 区块的数据已在一个比特币区块里，任何人都能读到。
比特币 6 个确认 BTC 最终 由比特币判定：任何快轨链都取代不了它，要推翻它只能重组比特币。

一笔操作几秒内就会快轨确认；携带其所在区块的交易被挖出后，它就已写入比特币；有了六个比特币确认，它就是最终的。

印记	含义	在 signet 上
快轨确认	出块者已把你的操作放进一个区块，每个节点都执行了它。	约 5 秒
已写入比特币	区块的数据已在一个比特币区块里，任何人都能读到。	通常是结算发出后的下一个比特币区块
BTC 最终	这些数据已有六个比特币确认，每个节点和索引器都依据比特币判定该区块已经最终。	写入比特币之后再过五个比特币区块，约 50 分钟

确认与最终性一页解释了每道印记各保证什么，以及各种付款分别要等多久。

在浏览器中

你需要 Unisat 或 Xverse 的浏览器扩展。signet 钱包页面连接的是托管的 signet 节点，所以除了钱包，什么都不用装。

设置比特币钱包

把钱包切换到 Bitcoin Signet，并使用 Taproot (P2TR) 地址。你的 Ksana 账户就是你的 Taproot 地址：KSA 和比特币共用这个地址，各自记在自己的链上。其他类型的地址不能持有 KSA。

Unisat：选择 Taproot 地址类型。
Xverse：账户的 Ordinals 地址就是 Taproot 地址，页面用的就是它。

页面会询问钱包当前设在哪个网络，其他网络一律拒绝，因为光凭 tb1… 地址分不清 signet 和 testnet。

连接 signet 钱包

打开 https://signet.ksana.network/，选择钱包，再选连接钱包，然后选中你的钱包。在扩展里批准这次连接。

页面只请求签名。它看不到你的密钥，也从不保管你的币。

领取测试 KSA

空钱包会在余额下方显示领取测试 KSA；收款页上也有同一个水龙头，按钮是从 signet 水龙头领取测试 KSA。两者都会给你的账户发 100 KSA。

水龙头每天给每个账户发一次。出块者一收录水龙头的转账，KSA 就会到账，只需几秒。

发送 KSA

选择发送，粘贴收款账户（一个 tb1p… 地址，或写成 64 位十六进制的账户），再填写金额。提交方式保持代付（路径 B）：手续费是一小笔 KSA，页面会给出建议值。

选择检查并签名，核对收款账户的首尾几位字符，再选签名并提交。钱包会请你签署一条消息（BIP322）。不动用任何比特币，也不付比特币手续费。

观察三道印记

签名之后，发送页会变成这笔操作的进度：待收录、快轨确认、已写入比特币、BTC 最终。几秒之内就会到达快轨确认。另外两道印记要跟着比特币出块，所以你可以让页面开着，或者过一会儿再回来：钱包的进行中列表和活动会一直跟踪，在区块浏览器中查看能看到涉及的每一笔比特币交易。

页面的其余功能见 Signet 钱包：路径 C、充值、区块浏览器，以及连接你自己的节点。

在命令行中

ksana-cli 是 Ksana 节点的命令行客户端。这里它通过 HTTPS 连接托管的 signet 节点；水龙头是一个普通的 HTTP API，用 curl 调用。

构建 ksana-cli

测试过的平台是 Ubuntu 22.04。安装 C 工具链、clang 和 libclang（RocksDB 要从源码编译）、git、curl、jq（其他页面用它从 JSON 里取字段）以及 rustup：

Ubuntu 22.04 上的前置依赖

sudo apt-get update
sudo apt-get install -y build-essential clang libclang-dev git curl jq
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain none
. "$HOME/.cargo/env"

克隆仓库并构建。rustup toolchain install 会读取 rust-toolchain.toml，安装固定版本的 Rust（1.98.1）。第一次构建要编译 RocksDB 和 wasmtime，在小机器上可能要半小时。

Shell

git clone https://github.com/ksana-in-bitcoin/Ksana
cd Ksana
rustup toolchain install
cargo build --release --locked -p ksana-cli
export PATH="$PWD/target/release:$PATH"
ksana-cli --version

输出

ksana-cli 0.1.0

生成密钥

先让 CLI 指向 signet 节点，再创建一个密钥文件。文件不存在时，key 会把一把新的随机私钥写进这个文件（权限 0600），并打印它的账户和地址；私钥本身从不打印。

Shell

export KSANA_RPC=https://signet.ksana.network/rpc
ksana-cli --chain signet key alice.key

输出

{
  "account": "44519c0982a42472e32bd9d90f0a82298697a190cd9c8ac2d23a2bee8d58d15f",
  "address": "tb1pg3geczvz5sj89cetm8vs7z5z9xrf0gvsekwg4skj8g47ar2c690surwrec",
  "internal_key": "95a204e1c34d497338d95c8cb901f8a8f71a0efb56faf7d46ae05a4f5fff9d78",
  "script": "512044519c0982a42472e32bd9d90f0a82298697a190cd9c8ac2d23a2bee8d58d15f"
}

address 和 account 是同样的 32 个字节，只是写法不同：前者是 Taproot 地址，后者是它的输出公钥的十六进制形式。--chain signet 让 key 打印 signet 地址；用在其他任何命令上，它会让 CLI 拒绝连接其他网络的节点。

密钥文件是这把私钥唯一的副本：谁读到它，谁就控制这个账户；丢了它，账户也就丢了。

向水龙头申请

把你的地址发给水龙头。请把下面的地址换成你的 key 命令打印出的 address。

Shell

curl -sS https://signet.ksana.network/faucet -H 'content-type: application/json' \
  --data '{"to": "tb1pg3geczvz5sj89cetm8vs7z5z9xrf0gvsekwg4skj8g47ar2c690surwrec"}'

输出

{"op_id":"92e22273a7fab8430c6ae16b69b1f649fa4056aa2a0c3f27d10bf38e77908a0d","to":"44519c0982a42472e32bd9d90f0a82298697a190cd9c8ac2d23a2bee8d58d15f","amount":"10000000000","nonce":"4"}

水龙头以一笔普通转账发出 100 KSA（10000000000 个最小单位：KSA 有 8 位小数），op_id 就是这笔转账的标识。节点一接受这笔转账，水龙头就会应答。每个账户每天可以申请一次；其他限制见公开 signet。

查看余额

几秒钟后，这笔转账就进了区块：

Shell

ksana-cli account @alice.key

输出

{
  "account": "44519c0982a42472e32bd9d90f0a82298697a190cd9c8ac2d23a2bee8d58d15f",
  "address": "tb1pg3geczvz5sj89cetm8vs7z5z9xrf0gvsekwg4skj8g47ar2c690surwrec",
  "at": {
    "hash": "81a22b58a74d0d6223cfb8c3c53a3ae21d13f0311c5d155f84863b5ba7be8639",
    "height": "261"
  },
  "balances": [
    {
      "amount": "10000000000",
      "asset": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "locked_fees": [],
  "nonce": "0"
}

@alice.key 代表该文件中那把密钥的账户；直接写地址或 64 位十六进制也可以。KSA 的资产 ID 是 64 个零。如果 balances 还是空的，等几秒再查一次。

发送 1 KSA

再生成一把密钥作为收款方，然后走路径 B 给它转 1 KSA（100000000 个最小单位），手续费为 1 个最小单位：

Shell

ksana-cli --chain signet key bob.key
ksana-cli --chain signet transfer --key alice.key --to @bob.key \
  --amount 100000000 --fee-token 1 --wait

输出

{
  "account": "44519c0982a42472e32bd9d90f0a82298697a190cd9c8ac2d23a2bee8d58d15f",
  "nonce": "0",
  "op_id": "501a6cba0a23521fbd72bfb704959b2720fce86d8edbac967fa4e611f0ca8728",
  "status": {
    "block": {
      "hash": "2f22a435469f702c2d23b1142ac39034d019fd406331a094485a789a1cc7d7b3",
      "height": "262"
    },
    "index": 0,
    "receipt": {
      "error": null,
      "events": [],
      "gas_used": "10000",
      "op_id": "501a6cba0a23521fbd72bfb704959b2720fce86d8edbac967fa4e611f0ca8728",
      "output": "",
      "success": true
    },
    "status": "fast_confirmed"
  }
}

--wait 会轮询节点，直到操作执行完毕；这一笔在发出约两秒后，于区块 262 快轨确认。--fee-token 是路径 B 的手续费，以 KSA 最小单位计，付给出块者：ksana-cli estimate-fee 会打印节点的建议值，目前在 signet 上是 1。

跟踪到最终

所在区块最终之后，这笔操作的状态就会从 fast_confirmed 变为 btc_final：

Shell

ksana-cli op 501a6cba0a23521fbd72bfb704959b2720fce86d8edbac967fa4e611f0ca8728

输出

{
  "block": {
    "hash": "2f22a435469f702c2d23b1142ac39034d019fd406331a094485a789a1cc7d7b3",
    "height": "262"
  },
  "index": 0,
  "receipt": {
    "error": null,
    "events": [],
    "gas_used": "10000",
    "op_id": "501a6cba0a23521fbd72bfb704959b2720fce86d8edbac967fa4e611f0ca8728",
    "output": "",
    "success": true
  },
  "status": "btc_final"
}

这中间，区块的结算会显示“已写入比特币”这道印记：携带这个区块以及它之前每一个区块的比特币交易全部被挖出后，settled 就变为 true。下面这份应答取自这些交易有四个确认的时候（jq 去掉了 txs，即原始交易）：

Shell

ksana-cli settlement 262 | jq 'del(.txs)'

输出

{
  "block": {
    "hash": "2f22a435469f702c2d23b1142ac39034d019fd406331a094485a789a1cc7d7b3",
    "height": "262"
  },
  "btc_final": false,
  "carrier": {
    "hash": "429f785a8e71515aed13acad24285fa441a9975f929a98c89ea30b0939e25bd2",
    "height": "264"
  },
  "carrier_account": "ccc06c3ce8d176b3c10138dd4e70873939a9c6dc05597f45aace147ef2c07d3d",
  "commit_txid": "ce91d3090919756230a46bcaf9195d375890e82b9229f8fb01f4014b7ea5c8ee",
  "commit_txid_rpc": "eec8a57e4b01f401fbf829922be89058375d19f9ca6ba4306275190909d391ce",
  "confirmed": {
    "block": "c48a4f4f1f7ce1e696becf01bbc5f15fdbf8ba7145b9badff31c7e7711000000",
    "confirmations": 4,
    "height": 326322,
    "txid": "a7cae8b07c1c5c8fe1258dd89205d75b5d4c81219d9843bfb4f35508b9bc4ae8"
  },
  "settled": true,
  "status": "confirmed",
  "txid": "a7cae8b07c1c5c8fe1258dd89205d75b5d4c81219d9843bfb4f35508b9bc4ae8",
  "txid_rpc": "e84abcb90855f3b4bf43989d21814c5d5bd70592d88d25e18f5c1c7cb0e8caa7"
}

区块 262 没有自己的结算：区块 264 的结算携带了它的数据（carrier），signet 区块 326,322 收录了这笔结算。到第六个确认时，btc_final 变为 true。txid_rpc 是揭示交易按区块浏览器的写法给出的 ID，比如 mempool.space 上的这一笔。

实际用时

本页的这笔转账发出于 2026 年 10 月 14 日 12:15:19 UTC。下表的时间是 ksana-cli 第一次显示各道印记的时刻；--wait 返回之后，每 30 秒用它查询一次。

印记	看到的时刻（UTC）	距发出
快轨确认，收进区块 262	12:15:21	2 秒
已写入比特币，进入 signet 区块 326,322	12:19:47	4.5 分钟
BTC 最终，于 signet 区块 326,327	13:23:53	68.6 分钟

这笔转账在第六个确认时变为最终，比“已写入比特币”这道印记晚 64 分钟：326,322 之后的五个 signet 区块，彼此间隔在 4 到 30 分钟之间。signet 平均十分钟出一个区块，所以预计要一个小时左右，有时更久。

下一步

Ksana 的工作原理快轨、写进比特币的结算，以及由比特币判定的最终性。
操作与手续费路径 B、路径 C 和充值，以及各自的花费。
ksana-cli 每一条命令：查询、合约、路径 C 和兑换。
运行节点自己跟随 signet，对照比特币检查每个区块，并挖矿。