KNOTS & Block Templates

Bitcoin and Lightning
1

Hey guys,

Recently installed KNOTS over Bitcoin Core.

I cant find where on the settings in KNOTS to adjust parameters for creating own custom block templates.

Have i missed something :thinking:?

Thanks

3

You’ll want to ssh in and grab this file but be reminded that it may be replaced on code upgrades as best I recall. Files are here vs gui:

cd ~/umbrel/app-data/bitcoin-knots/data/app$
aka
/home/umbrel/umbrel/app-data/bitcoin-knots/data/app

and look for the file named: bitcoin-config.json

Don’t forget to make a backup of the file first. cp bitcoin-config.json bitcoin-config.json.bak

Full Details

The configuration file for the Bitcoin Knots node running on your Umbrel setup is available for adjusting parameters for custom block templates. This file, located in ~/umbrel/app-data/bitcoin-knots/data/app, is used by the bitcoind service (from the docker-compose.yml) to configure Knots’ behavior, including block template generation.

How bitcoin-config.json Fits In

If you want to adjust parameters for creating custom block templates in Bitcoin Knots, the bitcoin-config.json file is Umbrel’s way of managing Knots’ configuration, serving a similar role to the traditional bitcoin.conf file but in JSON format for easier integration with Umbrel’s UI. It’s mounted in the server service’s volume (${APP_DATA_DIR}/data/app:/data) from the docker-compose.yml, and the bitcoind service reads it to set node policies.

This file contains several parameters directly tied to block template creation (e.g., blockmaxsize, blockmaxweight), which are used by Knots’ getblocktemplate RPC to generate templates for miners. The struggle probably comes from not realizing these settings are in bitcoin-config.json (not a GUI) or not knowing where to find the file on Umbrel. I had to look for them myself.

Key Block Template Parameters in bitcoin-config.json

Here are my findings on the settings relevant to block templates, explaining what they do, and suggesting how we can adjust them. These parameters shape the blocks Knots proposes to miners via getblocktemplate.

  1. blockmaxsize: 3985000
  • What It Does: Sets the maximum size (in bytes) of block templates. At 3.985 MB, this is close to Bitcoin’s 4 MB theoretical limit, allowing near-maximum block sizes.
  • Why It Matters: A larger blockmaxsize includes more transactions, maximizing fees but increasing block propagation time. A smaller size (e.g., 1 MB) prioritizes speed or filters low-fee transactions.
  • The Goal: If you want smaller blocks (e.g., to reduce spam or optimize for solo mining), you can lower this (e.g., blockmaxsize: 1000000 for 1 MB).
  • Example Use Case: A solo miner might set blockmaxsize: 500000 to create compact blocks, reducing the chance of orphaning during propagation.
  1. blockmaxweight: 3985000
  • What It Does: Sets the maximum weight (in weight units, post-SegWit) of block templates. At 3.985 million, it’s also near the 4M unit limit, aligning with blockmaxsize.
  • Why It Matters: Weight accounts for SegWit’s discounted witness data, so this controls the same block size limit but in a modern metric. It’s typically set equal to or slightly less than blockmaxsize converted to weight units.
  • The Goal: Adjust this alongside blockmaxsize for consistency (e.g., blockmaxweight: 1000000 for a 1 MB equivalent block).
  • Example Use Case: We might lower blockmaxweight to prioritize high-fee SegWit transactions, squeezing out legacy spam if we operated a shared pool; unlikely for home use.
  1. minrelaytxfee: 0.00001
  • What It Does: Sets the minimum fee rate (0.00001 BTC/kB, or 1 sat/vB) for transactions to be relayed or included in the mempool, indirectly affecting block templates.
  • Why It Matters: Knots uses this to filter transactions into the mempool, which getblocktemplate draws from. A higher minrelaytxfee (e.g., 10 sats/vB) excludes low-fee transactions, shaping leaner, high-value templates.
  • The Goal: Increase this (e.g., minrelaytxfee: 0.0001 for 10 sats/vB) to prioritize high-fee transactions in templates, especially if fighting spam like ordinals.
  • Example Use Case: Public Pool might benefit from minrelaytxfee: 0.00005 to ensure miners work on profitable blocks.
  1. rejectparasites: true
  • What It Does: Enables Knots’ anti-spam feature to reject transactions deemed “parasitic” (e.g., ordinals, inscriptions). This filters the mempool, affecting which transactions make it into block templates.
  • Why It Matters: This is a killer feature of Knots, letting users block mempool-clogging junk that Core blindly accepts. It directly customizes templates by excluding unwanted transactions.
  • The Goal: Keep this true to maintain clean templates, or tweak related policies (e.g., rejecttokens) for finer control.
  • Example Use Case: A miner annoyed by 1 MB inscription transactions can rely on rejectparasites: true to keep their templates focused on real payments.
  1. dustrelayfee: 0.00003
  • What It Does: Sets the minimum fee rate (3 sats/vB) for transactions to avoid being considered “dust” (low-value outputs uneconomical to spend). This influences mempool acceptance and template inclusion.
  • Why It Matters: Higher dustrelayfee filters tiny outputs, keeping templates efficient. Knots’ dustdynamic option (not shown here) could further refine this, but dustrelayfee is a baseline.
  • The Goal: Increase this (e.g., dustrelayfee: 0.0001) to exclude dust-heavy transactions, common in spam attacks.
  • Example Use Case: A solo miner might set dustrelayfee: 0.00005 to avoid wasting block space on unspendable outputs.
  1. blockreconstructionextratxn: 1000000
  • What It Does: Sets the maximum number of extra transactions Knots keeps for block reconstruction, which can affect template generation in edge cases (e.g., reorgs).
  • Why It Matters: This is advanced, but a high value ensures Knots can rebuild templates flexibly during network contention. Lowering it (e.g., 10000) might simplify templates but risks issues in volatile conditions.
  • The Goal: Likely fine as-is unless they’re optimizing for specific mining scenarios.

Other Relevant Settings

While not directly tied to getblocktemplate, these settings influence the mempool, which shapes block templates:

  • maxmempool: 300: Limits the mempool to 300 MB, affecting which transactions are available for templates. A smaller mempool (e.g., 100 MB) prioritizes high-fee transactions.
  • mempoolexpiry: 336: Transactions expire from the mempool after 336 hours (2 weeks). A shorter expiry (e.g., 24 hours) keeps the mempool fresh, impacting template quality.
  • datacarrier: true, datacarriersize: 42, acceptnonstddatacarrier: false: These control OP_RETURN data (used in inscriptions). The tight datacarriersize: 42 and acceptnonstddatacarrier: false limit spam, cleaning up templates alongside rejectparasites.

How to Adjust Block Template Settings

You can tweak these parameters to customize block templates for your needs (e.g., solo mining, Public Pool integration). Here’s the step-by-step:

  1. Edit bitcoin-config.json:
  • Access the file: nano ~/umbrel/app-data/bitcoin-knots/data/app/bitcoin-config.json.
  • Modify block template parameters. Example for smaller, high-fee blocks:

{ ... "blockmaxsize": 1000000, "blockmaxweight": 1000000, "minrelaytxfee": 0.0001, "rejectparasites": true, "dustrelayfee": 0.0001 ... }

  • Save the file.
  1. Restart the bitcoind Service:
  • Apply changes by restarting the Knots node:

docker-compose -f ~/umbrel/app-data/bitcoin-knots/docker-compose.yml restart bitcoind

  • The stop_grace_period: 15m30s ensures a clean shutdown.
  1. Test with RPC:
  • Use bitcoin-cli to generate a template and verify settings:

bitcoin-cli -rpcuser=${APP_BITCOIN_KNOTS_RPC_USER} -rpcpassword=${APP_BITCOIN_KNOTS_RPC_PASS} -rpcport=${APP_BITCOIN_KNOTS_RPC_PORT} getblocktemplate '{"blockmaxsize": 1000000, "minfeerate": 10}'

  • Credentials are set in the server service’s environment variables (${APP_BITCOIN_KNOTS_RPC_USER}, etc.).
  • Check the template’s size and transaction fees to confirm.
  1. Check Umbrel’s GUI:
  • Visit the Bitcoin Knots app via umbrel.umbrel (port 3005, via app_proxy). Look under “Settings” > “Node Policy” for options like rejectparasites or mempool settings. Umbrel may expose some JSON fields here, but bitcoin-config.json is the source of truth.
  1. Integrate with Public Pool (if applicable):
  • If you are running Public Pool, ensure its BITCOIN_RPC_URL points to this Knots node (${APP_BITCOIN_KNOTS_NODE_IP}:${APP_BITCOIN_KNOTS_RPC_PORT}).
  • The updated template settings (e.g., minrelaytxfee: 0.0001) will affect Public Pool’s blocks, making them leaner or more profitable.

Thanks for asking this one… I learned something as I looked it all up and might tweak my settings. What settings have you had success with and what do you recommend?

4

Amazingly detailed response - so helpful - fully answers my post - thanks again!

1 Like
5

This is so useful, thank you. I am solo mining and am tweaking my template based on above. If I reduce my blocs size to 500000, should my blockmaxweight also be 500000?

Thank again.