Understanding your configuration files and how to use them:

The topology.json file

Tells your node to which nodes in the network it should talk to. A minimal version of this file looks like this:
"Producers": [
"addr": "x.x.x.x",
"port": 3001,
"valency": 1
This means that your node will contact the node at ip x.x.x.x on port 3001.
valency tells the node how many connections your node should have. It only has an effect for dns addresses. If a dns address is given, valency governs how many resolved ip addresses we should maintain as active (hot) connections; for ip addresses, valency is used as a boolean value, where 0 means to ignore the address.
Your block-producing node must ONLY talk to your relay nodes, and the relay node should talk to other relay nodes in the network. Go to our forum channel to find out IP addresses and ports of peers.

The shelley-genesis.json file

The genesis file is generated with the cardano-cli by reading a genesis.spec.json file, which is out of scope for this document. But it is important because it is used to set:
  • genDelegs, a mapping from genesis keys to genesis delegates.
  • initialFunds, a mapping from the initial addresses to the initial values at those address.
  • MaxLovelaceSupply, the total amount of lovelaces in the blockchain.
  • startTime, the time of slot zero.
The genesis.json file looks like the one below.
"activeSlotsCoeff": 0.05,
"protocolParams": {
"poolDeposit": 500000000,
"protocolVersion": {
"minor": 0,
"major": 0
"minUTxOValue": 0,
"decentralisationParam": 1,
"maxTxSize": 16384,
"minPoolCost": 0,
"minFeeA": 44,
"maxBlockBodySize": 65536,
"minFeeB": 155381,
"eMax": 18,
"extraEntropy": {
"tag": "NeutralNonce"
"maxBlockHeaderSize": 1100,
"keyDeposit": 2000000,
"nOpt": 250,
"rho": 0.0022,
"tau": 0.05,
"a0": 0.3
"protocolMagicId": 42,
"genDelegs": {
"acded41a3329534b4a138a6262fc89ed84ab84a47439820027a1cfde": {
"delegate": "3006bbc11b9587f758f818e55d376173894f3119fa9f3bb506b39014",
"vrf": "4591768a404433121c891f4dcc72db18945f8f05c51b990c2ef32135f585ae5b"
"0e549da1e802e993fd67d0da974f8d64148417ded9ace34a38ee842e": {
"delegate": "17d2ab1bd33faeb975ce82f531cffb4c956acf14fc5fe62a30209b55",
"vrf": "f086cf388d1c9de15b5100da4198b5724ac65bab87ee25d1a7b34cbebd0dad36"
"a8fc4c8befb7a818fb86e68ec2bab42e90efb7833d6854e2d29570e7": {
"delegate": "65a6cf060d4b537ecca6b09690740cf7633941dd1de086c06652461f",
"vrf": "f92d64e5c607c3ff94ca8614781c5fc015d12c72c642b919e4d5665e765295b1"
"updateQuorum": 3,
"networkId": "Testnet",
"initialFunds": {
"60c307230dbe3be32364f2c3386c61b9a065b36635705f6feac72c4802": 1e+16,
"60be9af17be11a9c959721278f7a4be0161688df2ff1965444f8f50d53": 1000000000000000
"maxLovelaceSupply": 45000000000000000,
"networkMagic": 42,
"epochLength": 21600,
"staking": {
"pools": {},
"stake": {}
"systemStart": "2020-06-28T21:00:00Z",
"slotsPerKESPeriod": 3600,
"slotLength": 1,
"maxKESEvolutions": 120,
"securityParam": 108
Here is a brief description of each parameter. You can learn more in the spec​
The proportion of slots in which blocks should be issued.
Decay rate for pool deposits
The amount of a pool registration deposit
Accepted protocol versions
Percentage of blocks produced by federated nodes
Maximal transaction size
Stake pools cannot register/re-register their stake cost below this value
The linear factor for the minimum fee calculation
Maximal block body size
The minimum percent refund guarantee
The constant factor for the minimum fee calculation
Maximal block body size
The minimum percent refund guarantee
The constant factor for the minimum fee calculation
Epoch bound on pool retirement
Well, extra entropy =)
The amount of a key registration deposit
The deposit decay rate
Desired number of pools
Monetary expansion
The minimum percent pool refund
Treasury expansion
Pool's pledge influence
To identify the testnets
Time of slot 0
Mapping from genesis keys to genesis delegate
Determines the quorum needed for votes on the protocol parameter updates
Provides a mechanism for halting outdated nodes
Mapping address to values
The total number of lovelace in the system, used in the reward calculation.
To identify the testnet
Number of slots in an epoch.
Initial delegation
Number of slots in an KES period
In seconds
The maximum number of time a KES key can be evolved before a pool operator must create a new operational certificate
Security parameter k

The alonzo-genesis-json

This configuration files contains the cost model used by plutus scripts
"lovelacePerUTxOWord": 34482,
"executionPrices": {
"numerator" : 721,
"denominator" : 10000000
"numerator" : 577,
"denominator" : 10000
"maxTxExUnits": {
"exUnitsMem": 10000000,
"exUnitsSteps": 10000000000
"maxBlockExUnits": {
"exUnitsMem": 50000000,
"exUnitsSteps": 40000000000
"maxValueSize": 5000,
"collateralPercentage": 150,
"maxCollateralInputs": 3,
"costModels": {
"PlutusV1": {
"sha2_256-memory-arguments": 4,
"equalsString-cpu-arguments-constant": 1000,
"cekDelayCost-exBudgetMemory": 100,
"lessThanEqualsByteString-cpu-arguments-intercept": 103599,
"divideInteger-memory-arguments-minimum": 1,
"appendByteString-cpu-arguments-slope": 621,
"blake2b-cpu-arguments-slope": 29175,
"iData-cpu-arguments": 150000,
"encodeUtf8-cpu-arguments-slope": 1000,
"unBData-cpu-arguments": 150000,
"multiplyInteger-cpu-arguments-intercept": 61516,
"cekConstCost-exBudgetMemory": 100,
"nullList-cpu-arguments": 150000,
"equalsString-cpu-arguments-intercept": 150000,
"trace-cpu-arguments": 150000,
"mkNilData-memory-arguments": 32,
"lengthOfByteString-cpu-arguments": 150000,
"cekBuiltinCost-exBudgetCPU": 29773,
"bData-cpu-arguments": 150000,
"subtractInteger-cpu-arguments-slope": 0,
"unIData-cpu-arguments": 150000,
"consByteString-memory-arguments-intercept": 0,
"divideInteger-memory-arguments-slope": 1,
"divideInteger-cpu-arguments-model-arguments-slope": 118,
"listData-cpu-arguments": 150000,
"headList-cpu-arguments": 150000,
"chooseData-memory-arguments": 32,
"equalsInteger-cpu-arguments-intercept": 136542,
"sha3_256-cpu-arguments-slope": 82363,
"sliceByteString-cpu-arguments-slope": 5000,
"unMapData-cpu-arguments": 150000,
"lessThanInteger-cpu-arguments-intercept": 179690,
"mkCons-cpu-arguments": 150000,
"appendString-memory-arguments-intercept": 0,
"modInteger-cpu-arguments-model-arguments-slope": 118,
"ifThenElse-cpu-arguments": 1,
"mkNilPairData-cpu-arguments": 150000,
"lessThanEqualsInteger-cpu-arguments-intercept": 145276,
"addInteger-memory-arguments-slope": 1,
"chooseList-memory-arguments": 32,
"constrData-memory-arguments": 32,
"decodeUtf8-cpu-arguments-intercept": 150000,
"equalsData-memory-arguments": 1,
"subtractInteger-memory-arguments-slope": 1,
"appendByteString-memory-arguments-intercept": 0,
"lengthOfByteString-memory-arguments": 4,
"headList-memory-arguments": 32,
"listData-memory-arguments": 32,
"consByteString-cpu-arguments-intercept": 150000,
"unIData-memory-arguments": 32,
"remainderInteger-memory-arguments-minimum": 1,
"bData-memory-arguments": 32,
"lessThanByteString-cpu-arguments-slope": 248,
"encodeUtf8-memory-arguments-intercept": 0,
"cekStartupCost-exBudgetCPU": 100,
"multiplyInteger-memory-arguments-intercept": 0,
"unListData-memory-arguments": 32,
"remainderInteger-cpu-arguments-model-arguments-slope": 118,
"cekVarCost-exBudgetCPU": 29773,
"remainderInteger-memory-arguments-slope": 1,
"cekForceCost-exBudgetCPU": 29773,
"sha2_256-cpu-arguments-slope": 29175,
"equalsInteger-memory-arguments": 1,
"indexByteString-memory-arguments": 1,
"addInteger-memory-arguments-intercept": 1,
"chooseUnit-cpu-arguments": 150000,
"sndPair-cpu-arguments": 150000,
"cekLamCost-exBudgetCPU": 29773,
"fstPair-cpu-arguments": 150000,
"quotientInteger-memory-arguments-minimum": 1,
"decodeUtf8-cpu-arguments-slope": 1000,
"lessThanInteger-memory-arguments": 1,
"lessThanEqualsInteger-cpu-arguments-slope": 1366,
"fstPair-memory-arguments": 32,
"modInteger-memory-arguments-intercept": 0,
"unConstrData-cpu-arguments": 150000,
"lessThanEqualsInteger-memory-arguments": 1,
"chooseUnit-memory-arguments": 32,
"sndPair-memory-arguments": 32,
"addInteger-cpu-arguments-intercept": 197209,
"decodeUtf8-memory-arguments-slope": 8,
"equalsData-cpu-arguments-intercept": 150000,
"mapData-cpu-arguments": 150000,
"mkPairData-cpu-arguments": 150000,
"quotientInteger-cpu-arguments-constant": 148000,
"consByteString-memory-arguments-slope": 1,
"cekVarCost-exBudgetMemory": 100,
"indexByteString-cpu-arguments": 150000,
"unListData-cpu-arguments": 150000,
"equalsInteger-cpu-arguments-slope": 1326,
"cekStartupCost-exBudgetMemory": 100,
"subtractInteger-cpu-arguments-intercept": 197209,
"divideInteger-cpu-arguments-model-arguments-intercept": 425507,
"divideInteger-memory-arguments-intercept": 0,
"cekForceCost-exBudgetMemory": 100,
"blake2b-cpu-arguments-intercept": 2477736,
"remainderInteger-cpu-arguments-constant": 148000,
"tailList-cpu-arguments": 150000,
"encodeUtf8-cpu-arguments-intercept": 150000,
"equalsString-cpu-arguments-slope": 1000,
"lessThanByteString-memory-arguments": 1,
"multiplyInteger-cpu-arguments-slope": 11218,
"appendByteString-cpu-arguments-intercept": 396231,
"lessThanEqualsByteString-cpu-arguments-slope": 248,
"modInteger-memory-arguments-slope": 1,
"addInteger-cpu-arguments-slope": 0,
"equalsData-cpu-arguments-slope": 10000,
"decodeUtf8-memory-arguments-intercept": 0,
"chooseList-cpu-arguments": 150000,
"constrData-cpu-arguments": 150000,
"equalsByteString-memory-arguments": 1,
"cekApplyCost-exBudgetCPU": 29773,
"quotientInteger-memory-arguments-slope": 1,
"verifySignature-cpu-arguments-intercept": 3345831,
"unMapData-memory-arguments": 32,
"mkCons-memory-arguments": 32,
"sliceByteString-memory-arguments-slope": 1,
"sha3_256-memory-arguments": 4,
"ifThenElse-memory-arguments": 1,
"mkNilPairData-memory-arguments": 32,
"equalsByteString-cpu-arguments-slope": 247,
"appendString-cpu-arguments-intercept": 150000,
"quotientInteger-cpu-arguments-model-arguments-slope": 118,
"cekApplyCost-exBudgetMemory": 100,
"equalsString-memory-arguments": 1,
"multiplyInteger-memory-arguments-slope": 1,
"cekBuiltinCost-exBudgetMemory": 100,
"remainderInteger-memory-arguments-intercept": 0,
"sha2_256-cpu-arguments-intercept": 2477736,
"remainderInteger-cpu-arguments-model-arguments-intercept": 425507,
"lessThanEqualsByteString-memory-arguments": 1,
"tailList-memory-arguments": 32,
"mkNilData-cpu-arguments": 150000,
"chooseData-cpu-arguments": 150000,
"unBData-memory-arguments": 32,
"blake2b-memory-arguments": 4,
"iData-memory-arguments": 32,
"nullList-memory-arguments": 32,
"cekDelayCost-exBudgetCPU": 29773,
"subtractInteger-memory-arguments-intercept": 1,
"lessThanByteString-cpu-arguments-intercept": 103599,
"consByteString-cpu-arguments-slope": 1000,
"appendByteString-memory-arguments-slope": 1,
"trace-memory-arguments": 32,
"divideInteger-cpu-arguments-constant": 148000,
"cekConstCost-exBudgetCPU": 29773,
"encodeUtf8-memory-arguments-slope": 8,
"quotientInteger-cpu-arguments-model-arguments-intercept": 425507,
"mapData-memory-arguments": 32,
"appendString-cpu-arguments-slope": 1000,
"modInteger-cpu-arguments-constant": 148000,
"verifySignature-cpu-arguments-slope": 1,
"unConstrData-memory-arguments": 32,
"quotientInteger-memory-arguments-intercept": 0,
"equalsByteString-cpu-arguments-constant": 150000,
"sliceByteString-memory-arguments-intercept": 0,
"mkPairData-memory-arguments": 32,
"equalsByteString-cpu-arguments-intercept": 112536,
"appendString-memory-arguments-slope": 1,
"lessThanInteger-cpu-arguments-slope": 497,
"modInteger-cpu-arguments-model-arguments-intercept": 425507,
"modInteger-memory-arguments-minimum": 1,
"sha3_256-cpu-arguments-intercept": 0,
"verifySignature-memory-arguments": 1,
"cekLamCost-exBudgetMemory": 100,
"sliceByteString-cpu-arguments-intercept": 150000

The testnet-config.json file

The default testnet-config.json file that we downloaded is shown below.
This file has 4 sections that allow you to have full control on what your node does and how the informtion is presented.
NOTE Due to how the testnet-config.json file is generated, fields on the real file are shown in a different (less coherent) order. Here we present them in a more structured way

1 Basic Node Configuration.

The first section relates to the basic node configuration parameters. Make sure you have to Cardanoas the protocol, the correct path to the testnet-shelley-genesis.json file, RequiresMagicfor its use in a testnet. Note that in this example we are using the SimpleView. This will send the output to stdout. The other option is LiveView which uses a terminal multiplexer to generate a fancy view. We will cover this topic later.
"Protocol": "Cardano",
"GenesisFile": "testnet-shelley-genesis.json",
"RequiresNetworkMagic": "RequiresMagic",

2 Update parameteres

This protocol version number gets used by block producing nodes as part of the system for agreeing on and synchronising protocol updates.You just need to be aware of the latest version supported by the network. You dont need to change anything here.
"ApplicationName": "cardano-sl",
"ApplicationVersion": 0,
"LastKnownBlockVersion-Alt": 0,
"LastKnownBlockVersion-Major": 0,
"LastKnownBlockVersion-Minor": 0,

3 Tracing

Tracers tell your node what information you are interested in when logging, such as switches that you can turn ON or OFF according the type and quantity of information that you are interesetd in. This provides fairly coarse grained control, but it is relatively efficient at filtering out unwanted trace output.
The node can run in either the SimpleView or LiveView. The SimpleView uses standard output, optionally with log output. The LiveView is a text console with a live view of various node metrics.
TurnOnLogging: Enbles or disables logging overall.
TurnOnLogMetrics: Enables the collection of various OS metrics such as memory and CPU use. These metrics can be directed to the logs or monitoring backends.
setupBackends, defaultBackends, hasEKGand hasPrometheus: The system supports a number of backends for logging and monitoring. This setting lists the backends available to use in the configuration. The logging backend is called Katip. Also enable the EKG backend if you want to use the EKG or Prometheus monitoring interfaces.
setupScribes and defaultScribes: For the Katip logging backend we must set up outputs (called scribes) The available types of scribe are:
  • FileSK: for files
  • StdoutSK/StderrSK: for stdout/stderr
  • JournalSK: for systemd's journal system
  • DevNullSK
  • The scribe output format can be ScText or ScJson.
rotation The default file rotation settings for katip scribes, unless overridden in the setupScribes above for specific scribes.
"TurnOnLogging": true,
"TurnOnLogMetrics": true,
"ViewMode": "SimpleView",
"TracingVerbosity": "NormalVerbosity",
"minSeverity": "Debug",
"TraceBlockFetchClient": false,
"TraceBlockFetchDecisions": false,
"TraceBlockFetchProtocol": false,
"TraceBlockFetchProtocolSerialised": false,
"TraceBlockFetchServer": false,
"TraceChainDb": true,
"TraceChainSyncBlockServer": false,
"TraceChainSyncClient": false,
"TraceChainSyncHeaderServer": false,
"TraceChainSyncProtocol": false,
"TraceDNSResolver": true,
"TraceDNSSubscription": true,
"TraceErrorPolicy": true,
"TraceForge": true,
"TraceHandshake": false,
"TraceIpSubscription": true,
"TraceLocalChainSyncProtocol": false,
"TraceLocalErrorPolicy": true,
"TraceLocalHandshake": false,
"TraceLocalTxSubmissionProtocol": false,
"TraceLocalTxSubmissionServer": false,
"TraceMempool": true,
"TraceMux": false,
"TraceTxInbound": false,
"TraceTxOutbound": false,
"TraceTxSubmissionProtocol": false,
"setupBackends": [
"defaultBackends": [
"hasEKG": 12788,
"hasPrometheus": [
"setupScribes": [
"scFormat": "ScText",
"scKind": "StdoutSK",
"scName": "stdout",
"scRotation": null
"defaultScribes": [
"rotation": {
"rpKeepFilesNum": 10,
"rpLogLimitBytes": 5000000,
"rpMaxAgeHours": 24

4 Fine grained logging control

It is also possible to have more fine-grained control over the filtering of trace output, and to match and route trace output to particular backends. This is less efficient than the coarse trace filters above but provides much more precise control. options:
mapBackends This routes metrics matching specific names to particular backends. This overrides the defaultBackends listed above. Note that it is an override and not an extension so anything matched here will not go to the default backend, only to the explicitly listed backends.
mapSubtrace This section is more expressive, we are working on its documentation.
"options": {
"mapBackends": {
"cardano.node-metrics": [
"kind": "UserDefinedBK",
"name": "LiveViewBackend"
"cardano.node.BlockFetchDecision.peers": [
"kind": "UserDefinedBK",
"name": "LiveViewBackend"
"cardano.node.ChainDB.metrics": [
"kind": "UserDefinedBK",
"name": "LiveViewBackend"
"cardano.node.metrics": [
"kind": "UserDefinedBK",
"name": "LiveViewBackend"
"mapSubtrace": {
"benchmark": {
"contents": [
"subtrace": "ObservableTrace"
"#ekgview": {
"contents": [
"contents": "cardano.epoch-validation.benchmark",
"tag": "Contains"
"contents": ".monoclock.basic.",
"tag": "Contains"
"contents": "cardano.epoch-validation.benchmark",
"tag": "Contains"
"contents": "diff.RTS.cpuNs.timed.",
"tag": "Contains"
"contents": "#ekgview.#aggregation.cardano.epoch-validation.benchmark",
"tag": "StartsWith"
"contents": "diff.RTS.gcNum.timed.",
"tag": "Contains"
"subtrace": "FilterTrace"
"cardano.epoch-validation.utxo-stats": {
"subtrace": "NoTrace"
"cardano.node-metrics": {
"subtrace": "Neutral"
"cardano.node.metrics": {
"subtrace": "Neutral"
If you have any questions and suggestions while taking the lessons please feel free to ask in the forum and we will respond as soon as possible.
Copy link
On this page
The topology.json file
The shelley-genesis.json file
The alonzo-genesis-json
The testnet-config.json file
1 Basic Node Configuration.
2 Update parameteres
3 Tracing
4 Fine grained logging control