Protocol parameters

All protocol parameters live in one file, crates/ksana-primitives/src/params.rs: the struct Params and one constant for each network, DEVNET, SIGNET and MAINNET. This page names each parameter as the specification and the code comments do (CHAIN_ID, ANCHOR_DEPTH). The field in Params is the same name in lowercase, with a unit suffix on six of them (target_block_time_secs, asert_half_life_secs, max_future_block_time_secs, max_timestamp_ahead_of_anchor_secs, min_settlement_feerate_sat_vb, max_wasm_memory_bytes).

Amounts are in base units: KSA has 8 decimals, so 1 KSA is 100,000,000 base units. Times given in seconds or years assume the target of one unit of DAA score every 5 seconds. Mainnet has not launched: its values are the ones the specification freezes, and its section 13.1 gives the reason for each and marks the few still to be measured before launch, such as the Argon2id parameters.

The three networks

The project hosts two seed nodes, an indexer and the web wallet of the signet at signet.ksana.network (see Public signet). The node and the indexer pick the network with --chain devnet|signet|mainnet and default to devnet. ksana-cli takes the network from the chain ID of the node it talks to, and its --chain only states the network you expect.

The chain ID is written into every VmOp, so an operation signed for one network is invalid on the others. It is also part of the Argon2id salt of the proof of work.

What differs between networks

Every other parameter on this page has the same value on all three networks. Signet differs from devnet only in CHAIN_ID and ANCHOR_DEPTH, which a test in params.rs checks.

A path C transaction is force-included once it has NATIVE_CONFIRMATIONS + ANCHOR_DEPTH Bitcoin confirmations: 1 on devnet, 2 on signet and 5 on mainnet. A block anchored at Bitcoin height A must include the native transactions up to height A − NATIVE_CONFIRMATIONS + 1, and producers anchor ANCHOR_DEPTH blocks below their Bitcoin tip (crates/ksana-btc/src/native.rs).

Proof of work and difficulty

One Argon2id evaluation takes about 1 ms on one core of an ordinary CPU. On mainnet, 0x1f00ffff is a target of about 2^240: about 65,536 evaluations per block at the limit, so about 13 cores find a block every 5 seconds there. A genesis config can set a harder bits to match the hashrate expected at launch. Devnet and signet use 0x207fffff, the easiest target of Bitcoin regtest.

Two-speed difficulty. A block with entries has weight 1. The s-th empty block in a row on a selected chain has weight min(N × 2^(s − 1), N_MAX), with N = EMPTY_BLOCK_DIFFICULTY and N_MAX = MAX_EMPTY_BLOCK_WEIGHT: 12, 24, 48, 96, then 120 for every further one (Params::empty_block_weight). The weight divides the block’s PoW target, adds to the DAA score and counts the block’s reward slots, so an idle chain makes a block about every 1, 2, 4, 8 and then 10 minutes. See Mining.

Timestamps

A node checks a reception rule only when it receives a new block. A consensus rule holds for every block, including blocks synced from history or rebuilt from Bitcoin.

Block DAG

Pruning keeps a node’s memory bounded. The pruning point lies at least GhostdagParams::min_pruning_depth = 3 × (MERGE_DEPTH + GHOSTDAG_K) + 1 = 2,209 blue score below the pruning root (crates/ksana-consensus/src/ghostdag.rs). How far back the root is, and how often a node prunes, are local settings, listed under Local policy defaults.

Bitcoin anchoring and finality

Confirmations explains what these numbers mean for the time an operation takes to become final.

Data limits

The last three are in crates/ksana-primitives/src/lib.rs. These limits are consensus rules too: changing one is a consensus change, the same as changing a field of Params.

Gas and execution limits

The virtual machine adds fixed limits in crates/ksana-vm/src/limits.rs (and MAX_CALL_INPUT_BYTES in engine.rs):

The gas table, which prices every host function, is in Host functions.

Rewards and supply

KSA is issued only as block rewards. Each block takes as many reward slots as its weight, at the DAA scores it covers, and each slot pays the reward of its halving period. Period k lasts REWARD_HALVING_INTERVAL × 2^min(k, REWARD_INTERVAL_DOUBLINGS) DAA score and pays BLOCK_REWARD / 2^k per slot, rounded down to whole base units (Params::reward_period_at, block_reward_at).

On mainnet the last base unit is paid in period 28, and from DAA score 1,387,500,000 (about year 220) the reward is 0. All of mainnet’s slots together pay 20,999,999,600,000,000 base units, 4 KSA short of the cap. The bound Params::max_total_rewards = BLOCK_REWARD × REWARD_HALVING_INTERVAL × (REWARD_INTERVAL_DOUBLINGS + 2) is exactly KSA_MAX_SUPPLY on mainnet, so mainnet has no genesis allocation.

On devnet and signet every period lasts 25,228,800 DAA score (about 4 years) and the first pays 9.9 KSA per slot; the reward is 0 from DAA score 756,864,000 (period 30). The bound on their rewards is 499,530,240 KSA, which leaves at most 500,469,760 KSA for genesis allocations under their 1,000,000,000 KSA cap.

The carrier’s part is 0.21 KSA of a 4.2 KSA slot on mainnet and 0.495 KSA of a 9.9 KSA slot on signet; when no carrier qualifies, it stays with the producer.

Rewards and fees are paid at unlock, once the data of the block and of every block in its past has landed on Bitcoin. KSA and rewards explains the schedule, the carrier and unlocking.

Upgrades

Params::upgrades is empty on all three networks: blocks have protocol version 2 (BLOCK_VERSION) and accept VmOp version 2. An upgrade item raises the protocol version from a given DAA score and can set new values for these rules: BLOCK_GAS_LIMIT, NATIVE_MAX_GAS, the accepted VmOp versions, BLOCK_SHARE_BPS, BLOCK_SHARE_END, CARRIER_BPS and CARRIER_FEE_BPS. Other changes, such as new execution rules or encodings, branch on the protocol version in the code and activate with the same item.

Some parameters are fixed for the life of a network and stay out of the upgrade table: ASERT_HALF_LIFE, EMPTY_BLOCK_DIFFICULTY, MAX_EMPTY_BLOCK_WEIGHT, the Argon2id parameters, REWARD_INTERVAL_DOUBLINGS and CARRIER_REPOST_DELAY. A node reports its chain ID, protocol version and next scheduled upgrade with ksana_getChainInfo:

curl -s -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"ksana_getChainInfo","params":[]}' \
  https://signet.ksana.network/rpc | jq .result

{
  "chain_id": 1002,
  "tip": {
    "height": "281",
    "hash": "d18e91c9383400d27166695177decadb89399456e55d79eb6e6164d625edaf95"
  },
  "daa_score": "12199",
  "protocol_version": 2,
  "next_upgrade": null,
  "max_known_version": 2,
  "finalized": {
    "height": "241",
    "hash": "0cb65c0a51c1200757560f9ed1a2aa28f5a01a236bbdda8005120eb609a8ae6b"
  }
}

The DAA score runs far ahead of the height because the signet was mostly idle: its empty blocks weigh 12 to 120 each.

Genesis configurations

Every node and indexer of a network starts from the same genesis config, a JSON file (crates/ksana-execution/src/genesis_file.rs). A data directory records the config’s fingerprint and refuses to open with another one.

• devnet has no committed file: devnet/init.sh writes a new one, with new random keys, each time the devnet starts from scratch.
• signet uses the committed signet/genesis.json. Its bits expects about 10,000 Argon2id evaluations per block, sized for the two seed nodes that mine on one thread each (signet/ksana-signet.sh). The first allocation, 100,000,000 KSA, funds the faucet; the second, 10,000,000 KSA, belongs to the operator.
• mainnet has only the template mainnet/genesis.json. A node or indexer refuses any config whose block share account is the placeholder KSANA_BLOCK_SHARE_ACCOUNT_TBD___, and on mainnet it also requires a block share account, no allocations, and a real anchor and timestamp.

{
  "timestamp": "1791922279",
  "btc_anchor": {
    "height": 326234,
    "hash": "125a733363723ca64466266cabd12c462c62480b346330560ac79ef801000000"
  },
  "bits": 520523192,
  "allocations": [
    {
      "account": "de6603f052fd5bfaae5678a2a20ae6ae4fe4ae00c89db70a2efea7429851afc0",
      "amount": "10000000000000000"
    },
    {
      "account": "6431409abb9b8434defe68b0e066cf76610ac7b1cf49f2d02bc807543877dc0e",
      "amount": "1000000000000000"
    }
  ],
  "block_share_account": "0073719af1ae0718ca4fde1055e6c5c34157eefd54302c9b19deb28927ce8d8c"
}

The anchor hash is in Bitcoin’s internal byte order, the reverse of what bitcoin-cli getblockhash prints. A consensus change before mainnet restarts the signet from a new genesis config, and balances do not carry over.

Local policy defaults

These are a node’s own settings, not consensus rules: each operator can change them, and nodes with different settings still agree on the chain. Run a node explains the flags.

A read-only ksana_call runs with at most BLOCK_GAS_LIMIT gas, and a node runs at most 4 of them at a time.

Default ports

The devnet in Docker Compose publishes bitcoind on 18443 (P2P on 18444), its three nodes on 18545 to 18547 and its indexer on 18548. The signet’s first seed node is {{signet.p2p}}, and its other endpoints are listed on Public signet.