darkfi/script/research/fee-model

Fee Calibration

Utilities for calibrating fee constants from resource usage measurements.

• bench / db_bench measure primitive timings (WASM, hashes, sigs, ZK, sled I/O) in nanoseconds. These derive the measured gas constants in src/validator/fees.rs.
• capacity measures per-tx validator gas (verify_fees=false), i.e. the base cost excluding the fee call. It adds FEE_CALL_GAS to report gas_per_tx_with_fee.

bench

Low-level microbenchmark of WASM opcodes, hashes, signatures, and ZK circuits.

make bench

Writes bench_results.json (JSON on stdout, progress on stderr).

ZK proof files must be generated first:

cd ../zkvm-metering/generator
make
./generator

What it measures:

Operation	Iterations
WASM opcode (add)	1000000
Poseidon, Sinsemilla hashes	1000000
Pallas Schnorr signature verify	1000000
ZK circuit verify (k=11, k=14)	1000
ZK circuit compile (verifying key build, k=11, k=14)	1000

Timed closures exclude RNG, allocation, and formatting so the numbers reflect the primitive. ZK stats are reported per-row in nanoseconds.

In addition to the aggregate stats, bench emits a circuits map keyed by contract circuit name (money/dao *.zk.bin). Each entry records k, compile_p50_ns_per_row, vk_size_bytes, opcodes_count, witnesses_count, and literals_count.

db_bench

Standalone database microbenchmark. Measures sled I/O across four scenarios (set new key, overwrite, get, contains_key) and eight payload sizes (32b to 8KiB), fits a linear regression of ns/byte, and expresses the slopes as ratios against the WASM-add baseline.

make db_bench

Writes db_bench_results.json.

capacity

Measures per-tx gas and per-tx wall-clock time (verify + apply) across the scenarios below. Each scenario builds a batch of prebuilt transactions and runs it through the validator. Output is raw measurements (gas_per_tx, secs_per_tx).

Scenarios:

Scenario	Shape
transfer_simple	transfer 1-in/2-out
transfer_20in_2out	transfer 20-in/2-out
transfer_1in_20out	transfer 1-in/20-out
dao_propose_20recip	DAO propose, 20 recipients
dao_exec_20recip	DAO exec, 20 recipients
dao_vote	DAO vote
otc_swap	OTC swap
token_mint	token mint
dao_mint	DAO mint
deploy_512kb	deploy 512 KiB WASM
deploy_1024kb	deploy 1024 KiB WASM
mixed	~78% transfers, 10% votes, 6% execs, 4% mints, 2% deploys

Run with:

make capacity

make capacity runs all scenarios. Set MONEY_WASM_PATH only when the money contract WASM is not at the default source-tree path:

MONEY_WASM_PATH=/path/to/darkfi_money_contract.wasm make capacity

Timing: verification_secs is the median of 3 verify-only (write=false) runs. apply_secs comes from one verify+apply (write=true) pass, as max(0, apply_total - verification_secs). Verify-only trials reuse the same base state because a write=true run spends the prebuilt coins and would break the next trial. No explicit warmup is needed: building the transactions already executes each one once.

machine_info (CPU model, cores, RAM, disk type) is auto-detected and included in the output so runs from different machines can be grouped.

Example output:

{
  "machine_info": { "cpu_model": "...", "physical_cores": 12, ... },
  "results": [
    {
      "scenario": "transfer_20in_2out",
      "gas_per_tx": 96336180.0,
      "secs_per_tx": 0.326,
      "tps": 3.07
    }
  ]
}

Each result object also includes gas_per_tx_with_fee, fee_overhead_gas, verify_fees, block_gas_limit, op_shape, tx_count, gas_used, verification_secs, apply_secs, and total_secs (omitted above for brevity).

Recalibration

The gas-model constants live in src/validator/fees.rs, plus FEE_CALL_GAS in src/contract/money/src/client/fee_v1.rs. They are expressed relative to a single WASM opcode (the wasm_add baseline). The ratios are approximate. A given constant set should be calibrated against the target validator hardware profile.

Where each constant comes from

wasm_add below means the p50 of one WASM opcode (wasm_add.p50_ns from bench, or wasm_add_p50_ns from db_bench). db_bench pre-divides its slopes by wasm_add, so its ratios.* fields are already in gas units.

Constant	Benchmark	Read from	Convert
POSEIDON_HASH_GAS	bench	poseidon_hash.p50_ns	/ wasm_add.p50_ns
SINSEMILLA_HASH_GAS	bench	sinsemilla_hash.p50_ns	/ wasm_add.p50_ns
PALLAS_SCHNORR_VERIFY_GAS	bench	pallas_signature_verify.p50_ns	/ wasm_add.p50_ns
VERIFY_GAS_PER_ROW	bench	zk_verify.*.p50_ns	/ wasm_add.p50_ns (already per-row)
COMPILE_GAS_PER_ROW	bench	zk_compile.*.p50_ns	/ wasm_add.p50_ns (already per-row)
READ_GAS_PER_BYTE	db_bench	ratios.read_per_byte	already in gas units
WRITE_GAS_PER_BYTE	db_bench	ratios.write_new_per_byte	already in gas units
STATE_GROWTH_GAS	db_bench	db_set_new.intercept_ns	/ wasm_add_p50_ns

FEE_CALL_GAS is set conservatively (see fee_v1.rs and doc/src/arch/fees.md); it does not require recalibration when gas constants change because it carries deliberate headroom.

Re-deriving all constants from fresh measurements

1. make bench and make db_bench (CPU-pinned): measure primitive timings, then re-derive each constant from the ratios above.
2. make capacity: record the new gas_per_tx per scenario.

secs_per_tx (timing) only changes if the hardware or implementation changed, not from constant edits.

Changing one constant (e.g. STATE_GROWTH_GAS 20k -> 40k)

A constant edit does not require re-running bench / db_bench — those measure time, not gas. Gas is computed from the constants at runtime, so only the gas-valued outputs drift. After editing the constant in src/validator/fees.rs:

1. make capacity: every scenario that inserts keys gets a new gas_per_tx; secs_per_tx is unchanged.
2. Re-check the block gas limit L against the new gas_per_tx (below).

Redo capacity after any fees.rs edit.

Calibration

Pick the block gas limit L by combining gas_per_tx (hardware-independent) with secs_per_tx per hardware tier:

time_bound_tps(h, s) = 1 / secs_per_tx(h, s)
gas_bound_tps(L, s)  = L / gas_per_tx(s)
effective_tps(h, s, L) = min(time_bound_tps, gas_bound_tps)

Run capacity on each target hardware tier, sweep candidate L values, and pick the largest L where the slowest tier's worst-case block still fits within the block time. Any larger and validators get blocks they cannot process in time.