Quickstart

Set up a Bitcoin wallet

Switch the wallet to Bitcoin Signet and use a Taproot (P2TR) address. Your Ksana account is your Taproot address: KSA and bitcoin share it, each on its own chain. Other address types cannot hold KSA.

• Unisat: choose the Taproot address type.
• Xverse: the account’s Ordinals address is the Taproot one, and the page uses it.

The page asks the wallet which network it is set to and refuses any other, because a tb1… address alone does not tell signet from testnet.

Connect to the signet wallet

Open https://signet.ksana.network/, choose Wallet, then Connect wallet, and pick your wallet. Approve the connection in the extension.

The page asks only for signatures. It never sees your keys and never holds your coins.

Claim test KSA

An empty wallet shows Claim test KSA under its balance; the Receive page has the same faucet as Get test KSA from the signet faucet. Either sends 100 KSA to your account.

The faucet pays each account once a day. The KSA arrives in a few seconds, as soon as a producer includes the faucet’s transfer.

Send KSA

Choose Send, paste a recipient (a tb1p… address, or an account as 64 hex digits) and an amount. Leave the way to submit at Sponsored (path B): the fee is a small amount of KSA, and the page suggests one.

Choose Review and sign, check the recipient’s first and last characters, then Sign and submit. The wallet asks you to sign one message (BIP322). No bitcoin moves and no Bitcoin fee is paid.

Watch the three marks

After you sign, the Send page turns into the operation’s progress: Pending, Fast-confirmed, On Bitcoin, BTC final. It reaches Fast-confirmed within seconds. The other two follow the Bitcoin blocks, so leave the page open or come back later: the wallet’s In progress list and Activity keep track, and View in explorer shows each Bitcoin transaction involved.

Build ksana-cli

The tested platform is Ubuntu 22.04. Install a C toolchain, clang and libclang (RocksDB is compiled from source), git, curl, jq (other pages use it to pick fields out of JSON) and rustup:

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"

Clone the repository and build. rustup toolchain install reads rust-toolchain.toml and installs the pinned Rust (1.98.1). The first build compiles RocksDB and wasmtime and can take half an hour on a small machine.

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

Make a key

Point the CLI at the signet node, then create a key file. key writes a new random secret key to the file (mode 0600) when the file does not exist, and prints its account and address; it never prints the secret.

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 and account are the same 32 bytes, written two ways: the Taproot address and its output key in hex. --chain signet makes key print a signet address; on every other command it makes the CLI refuse a node on another network.

The key file is the only copy of the secret key: anyone who reads it controls the account, and losing it loses the account.

Ask the faucet

Send your address to the faucet. Replace the address below with the address your key command printed.

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

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

The faucet sends 100 KSA (10000000000 base units: KSA has 8 decimals) as an ordinary transfer, and op_id identifies it. It answers as soon as the node accepts the transfer. Each account can ask once a day; Public signet lists the other limits.

Check your balance

A few seconds later the transfer is in a block:

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 stands for the account of the key in that file; an address or 64 hex digits work too. The asset ID of KSA is 64 zeros. If balances is still empty, wait a few seconds and ask again.

Send 1 KSA

Make a second key to send to, then transfer 1 KSA (100000000 base units) to it on path B with a fee of 1 base unit:

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 polls the node until the operation is executed; this one was fast-confirmed in block 262 about two seconds after it was sent. --fee-token is the path B fee in KSA base units, paid to the producer: ksana-cli estimate-fee prints the node’s suggestion, which is 1 on the signet today.

Follow it to final

The status of the operation changes from fast_confirmed to btc_final once its block is final:

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"
}

In between, the block’s settlement shows the on-Bitcoin mark: settled turns true once the Bitcoin transactions carrying this block, and every block before it, are mined. This answer is from when they had four confirmations (jq leaves out txs, the raw transactions):

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"
}

Block 262 had no settlement of its own: the settlement of block 264 carried its data (carrier), and signet block 326,322 included it. btc_final turns true with the sixth confirmation. txid_rpc is the reveal transaction’s ID as explorers write it, as in this one on mempool.space.