### Start Cardano Node

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/libs/ledger-state/README.md

Starts the Cardano node with specified configuration and database paths. Ensure the CARDANO_NODE_SOCKET_PATH is set.

```shell
$ export CARDANO_NODE_SOCKET_PATH="${CARDANO_DATA}/db/node.socket"
$ cardano-node run \
    --topology "${CARDANO_DATA}/topology.json" \
    --config "${CARDANO_DATA}/config.json" \
    --database-path "${CARDANO_DATA}/db" \
    --socket-path "${CARDANO_NODE_SOCKET_PATH}" \
    --host-addr 0.0.0.0 \
    --port 3001 &
```

--------------------------------

### Run Cardano Node Mainnet

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/CONTRIBUTING.md

Start a Cardano node to build up the necessary data for analysis. This process can take a significant amount of time.

```bash
nix run .#mainnet/node
```

--------------------------------

### Nix Command to Enter Profiling Shell

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/HowToProfileLedger.md

Command to start the nix development shell with profiling enabled.

```bash
nix develop .#profiling
```

--------------------------------

### Example Token Bundle Structure

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/doc/explanations/token-bundles.md

This snippet shows the structure of a token bundle named TB_Example, containing tokens from different policy IDs.

```default
{ 
        NFLPlayerCardsPolicyID {
                (SomeNFLPlayerCard, 1),
                (SomeOtherNFLPlayerCard, 1),
                (YetAnotherNFLPlayerCard, 1)}

        RushConcertPolicyID {
                (Tickets, 500),
                (VIPTickets, 50)}
}
```

--------------------------------

### Example Profiling Report

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/HowToProfileLedger.md

A sample of the profiling report generated after running tests with profiling enabled. It shows time and allocation statistics for different cost centers.

```text
----------------------------------------------------------------------------------------------------------
Fri May  6 14:02 2022 Time and Allocation Profiling Report  (Final)

	   cardano-ledger-test +RTS -i60 -p -RTS

	total time  =       51.05 secs   (51050 ticks @ 1000 us, 1 processor)
	total alloc = 109,620,447,376 bytes  (excludes profiling overheads)

COST CENTRE               MODULE                                SRC                                                            %time %alloc

showsPrec                 Cardano.Ledger.Alonzo.TxInfo          src/Cardano/Ledger/Alonzo/TxInfo.hs:504:13-16                   10.3   19.9
evalScripts               Cardano.Ledger.Alonzo.PlutusScriptApi src/Cardano/Ledger/Alonzo/PlutusScriptApi.hs:(231,1)-(247,55)    7.5    1.6
evalScripts.endMsg        Cardano.Ledger.Alonzo.PlutusScriptApi src/Cardano/Ledger/Alonzo/PlutusScriptApi.hs:(240,7)-(246,11)    6.5   17.8
show                      Cardano.Ledger.Alonzo.Scripts         src/Cardano/Ledger/Alonzo/Scripts.hs:202:3-74                    6.1   14.8
blake2b_libsodium         Cardano.Crypto.Hash.Blake2b           src/Cardano/Crypto/Hash/Blake2b.hs:(37,1)-(43,104)               2.6    1.0
decodeAddrStateT          Cardano.Ledger.CompactAddress         src/Cardano/Ledger/CompactAddress.hs:(287,1)-(304,40)            2.3    1.2
splitSMGen                System.Random.SplitMix                src/System/Random/SplitMix.hs:(225,1)-(229,31)                   1.4    3.2
explainPlutusFailure.line Cardano.Ledger.Alonzo.TxInfo          src/Cardano/Ledger/Alonzo/TxInfo.hs:(665,13)-(673,19)            1.4    2.3
toBuilder                 Codec.CBOR.Write                      src/Codec/CBOR/Write.hs:(102,1)-(103,57)                         1.3    0.5
genValidatedTxAndInfo     Test.Cardano.Ledger.Generic.TxGen     src/Test/Cardano/Ledger/Generic/TxGen.hs:(759,1)-(947,55)        1.3    0.1
runE                      Data.Coders                           src/Data/Coders.hs:(566,1)-(577,20)                              1.3    0.7
showsPrec                 Cardano.Ledger.Alonzo.TxInfo          src/Cardano/Ledger/Alonzo/TxInfo.hs:467:13-16                    1.2    3.2
hashWith                  Cardano.Crypto.Hash.Class             src/Cardano/Crypto/Hash/Class.hs:(125,1)-(129,13)                1.2    0.5
genKeyHash.\              Test.Cardano.Ledger.Generic.GenState  src/Test/Cardano/Ledger/Generic/GenState.hs:369:37-83            1.1    0.4
serializeEncoding         Cardano.Binary.Serialize              src/Cardano/Binary/Serialize.hs:(61,1)-(67,49)                   0.8    2.1
toLazyByteString          Codec.CBOR.Write                      src/Codec/CBOR/Write.hs:86:1-49                                  0.7    4.9
---------------------------------------------------------------------------------------------------------------------

```

--------------------------------

### Example of Updated Changelog Section

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/RELEASING.md

Illustrates how a CHANGELOG.md file might look after the bump-changelogs.sh script is run, showing a new empty section for the next patch version.

```markdown
# Version history for `cardano-ledger-core`

## 1.20.1.2

*

## 1.20.1.1

...
```

--------------------------------

### Generate CHAIN Trace Example

Source: https://github.com/intersectmbo/cardano-ledger/wiki/Property-Test-Guide

Illustrates the sequential generation of states and signals for a CHAIN trace, showing how ChainState and Block are produced iteratively. This is fundamental for testing ledger rules.

```haskell
traceFromInitState @(CHAIN era) testGlobals tl (genEnv p) (Just $ mkGenesisChainState (genEnv p))
```

--------------------------------

### Run Fast Test Scenario

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/CONTRIBUTING.md

Execute a predefined test scenario using the --scenario flag. This example runs the 'Fast' scenario for the Shelley test suite.

```shell
cabal test cardano-ledger-shelley-test --test-options --scenario=Fast
```

--------------------------------

### Deriving NetworkMagic from ProtocolMagic

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/eras/byron/ledger/impl/doc/network-magic.md

Example function demonstrating how to derive the NetworkMagic value from the ProtocolMagic configuration, ensuring consistency.

```haskell
makeNetworkMagic :: ProtocolMagic -> NetworkMagic
makeNetworkMagic (ProtocolMagic pmId reqNetMagic) = case reqNetMagic of
  RequiresNoMagic -> NetworkMainOrStage
  RequiresMagic   -> NetworkTestnet pmId
```

--------------------------------

### Changelog for No Changes

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/RELEASING.md

Example of a changelog entry indicating no changes for a specific package version.

```markdown
# Version history for `cardano-ledger-conway`

## 1.2.0.1

*
```

--------------------------------

### Example PR Table

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/implementation-decisions.md

Illustrates the format for listing related Pull Requests (PRs) for a decision, including their numbers and base branches.

```markdown
| Number                                       | Base            |
| ---                                          | ---             |
| https://github.com/some/other-repo/issues/14 | `develop`       |
| #42                                          | `release/2.0.0` |
```

--------------------------------

### Example CHANGELOG.md Entry for Unreleased Version

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/RELEASING.md

Illustrates the structure of the top-most unreleased version entry in a package's CHANGELOG.md file, showing a version bump compared to the latest released version.

```markdown
# Version history for `cardano-ledger-core`

## Unreleased

### Added

*   A new feature was added.

### Changed

*   An existing feature was modified.

### Removed

*   A feature was removed.

## 1.2.3.0 -- 2023-01-01

### Changed

*   This is the latest released version.

```

--------------------------------

### Changelog Versioning Example: Major Overhaul

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/RELEASING.md

Describes the case where the current development version is `cardano-ledger-core-2.0.0.0`, indicating a major overhaul, and thus no version bumping is required.

```markdown
* If the current version is `cardano-ledger-core-2.0.0.0`. There was a complete
  overhaul. Definitely nothing needs to be bumped. :grin:
```

--------------------------------

### Release Specific Package to CHaP

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/RELEASING.md

Example of releasing a specific package (cardano-ledger-core) from a given commit SHA to CHaP. Ensure you supply a commit SHA, not a branch name.

```shell
$ ./scripts/add-from-github.sh https://github.com/intersectmbo/cardano-ledger deadbeef libs/cardano-ledger-core ...
```

--------------------------------

### Changelog Versioning Example: No Action Needed

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/RELEASING.md

Explains the scenario where no version update is needed in the changelog because the current development version (`cardano-ledger-core-1.3.0.0`) already reflects breaking changes since the last release.

```markdown
* If the current version is `cardano-ledger-core-1.3.0.0`. That means currently released
  version to CHaPs is `cardano-ledger-core-1.2.x.x`. There is nothing to do, the version
  on `master` already contains some other breaking changes since the last release to CHaPs
```

--------------------------------

### Build All Specs with Nix

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/README.md

Run this command from the root directory to build all LaTeX documents and executable specifications.

```shell
nix build .#specs
```

--------------------------------

### Handle Late Start in Pulsing Computation

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/docs/reward-calculation/HowRewardCalculationWorks.md

This snippet handles the scenario where the computation starts too late. It initiates a pulser, completes it, and logs a 'Starting too late' event.

```haskell
let pulser = startStep slotsPerEpoch b es maxsupply asc k
(reward, event) <- liftSTS $ completeStep pulser
tellRupd "Starting too late" (RupdEvent (succ e) event)
pure (SJust reward)
```

--------------------------------

### Build Documentation Site with Nix

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/doc/README.md

Builds the documentation site using the top-level Nix command. This is an alternative to building within a nix develop shell.

```default
nix build .#doc.site
```

--------------------------------

### Build Executable Specifications with Nix

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/eras/byron/README.md

Navigate to the directory containing the executable specifications and run this command to build them using Nix.

```shell
nix build
```

--------------------------------

### NewEpoch Event Structure

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/docs/LedgerEvents.md

Signals the start of a new epoch. This event occurs only on epoch boundaries.

```haskell
data LedgerEvent = NewEpoch Epoch
  deriving (Show, Eq)
```

--------------------------------

### Build LaTeX Document with Make

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/README.md

Navigate to the specific LaTeX directory and run this command within a Nix shell to build the document.

```shell
cd <myLaTexDir>
nix develop --command make
```

--------------------------------

### Build Documentation Site with Sphinx

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/doc/README.md

Builds the Sphinx documentation site from a nix develop shell. Ensure you are in the project's root directory.

```default
sphinx-build -n . _build
```

--------------------------------

### Changelog for Breaking Changes

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/RELEASING.md

Example of a changelog entry indicating breaking changes for a specific package version.

```markdown
# Version history for `cardano-ledger-conway`

## 1.3.0.0

* breaking changes
```

--------------------------------

### Configure and Run Performance Benchmark

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/libs/ledger-state/README.md

Sets environment variables for performance benchmark inputs and runs the benchmark, saving results to a CSV file. The UTxO path is optional for some benchmarks.

```shell
$ export BENCH_GENESIS_PATH=${CARDANO_DATA}/shelley-genesis.json
$ export BENCH_LEDGER_STATE_PATH=${CARDANO_DATA}/new-epoch-state.bin
$ export BENCH_UTXO_PATH=${CARDANO_DATA}/utxo.hex
$ cabal bench ledger-state:performance --benchmark-option=--csv=ledger-state:performance.csv
```

--------------------------------

### Build CHaP Repository with Foliage

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/REVISIONING.md

Build the CHaP repository locally using foliage. This command is used to build the repository and write metadata.

```bash
nix develop --command bash -c "foliage build -j 0 --write-metadata"
```

--------------------------------

### Run All Benchmarks

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/eras/shelley/test-suite/bench/README.md

Execute the entire benchmark suite using Stack. This is the default command to run all defined benchmarks.

```shell
stack bench
```

--------------------------------

### Changelog Versioning Example: Breaking Change

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/RELEASING.md

Illustrates how to update the version in the changelog for a breaking change when the current development version is `cardano-ledger-core-1.2.3.5`.

```markdown
* If the current version is set to `cardano-ledger-core-1.2.3.5`. We see that the patch
  version is bumped (not zero), that means that the latest version released is
  `cardano-ledger-core-1.2.3.4`, so you update it to `cardano-ledger-core-1.3.0.0`,
  because your changes break stuff
```

--------------------------------

### Reward Timing Determination

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/docs/reward-calculation/HowRewardCalculationWorks.md

Determines the appropriate timing for reward calculation based on the current slot relative to the start and end slots for pulsing.

```haskell
-- | The Goldilocks labeling of when to do the reward calculation.
data RewardTiming = RewardsTooEarly | RewardsJustRight | RewardsTooLate

determineRewardTiming :: SlotNo -> SlotNo -> SlotNo -> RewardTiming
determineRewardTiming currentSlot startAfterSlot endSlot
  | currentSlot > endSlot = RewardsTooLate
  | currentSlot <= startAfterSlot = RewardsTooEarly
  | otherwise = RewardsJustRight
```

--------------------------------

### Build and Run Tests with Nix

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/eras/byron/README.md

Use these Nix commands to build or run tests for the executable specifications.

```shell
nix build .#tests
```

```shell
nix run .#tests
```

--------------------------------

### Build LaTeX Documents with Nix

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/eras/byron/README.md

Use this command to build the LaTeX documentation. It requires a Nix development shell.

```shell
nix develop --command make
```

--------------------------------

### Run Benchmarks with HTML Output

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/eras/shelley/test-suite/bench/README.md

Execute benchmarks and generate an HTML report of the results. Specify the output file using '--output'.

```shell
stack bench --ba --output=bench.html
```

--------------------------------

### Enable Nix Shell with Profiling

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/CONTRIBUTING.md

Open a nix shell within the ouroboros repository base directory with profiling enabled.

```bash
~/ouroboros-network$ nix-shell --arg config "{ haskellNix.profiling = true; }"
```

--------------------------------

### Run Specific Shelley Golden Tests

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/CONTRIBUTING.md

Use the -p flag with an awk pattern to run specific tests. This example runs the golden tests for the Shelley ledger.

```shell
cabal test cardano-ledger-shelley-test --test-options="-p golden"
```

--------------------------------

### Download Cardano Mainnet Configuration Files

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/libs/ledger-state/README.md

Downloads essential configuration files for running a Cardano node on the mainnet.

```shell
curl -O -J https://book.play.dev.cardano.org/environments/mainnet/config.json
curl -O -J https://book.play.dev.cardano.org/environments/mainnet/db-sync-config.json
curl -O -J https://book.play.dev.cardano.org/environments/mainnet/submit-api-config.json
curl -O -J https://book.play.dev.cardano.org/environments/mainnet/topology.json
curl -O -J https://book.play.dev.cardano.org/environments/mainnet/byron-genesis.json
curl -O -J https://book.play.dev.cardano.org/environments/mainnet/shelley-genesis.json
curl -O -J https://book.play.dev.cardano.org/environments/mainnet/alonzo-genesis.json
curl -O -J https://book.play.dev.cardano.org/environments/mainnet/conway-genesis.json
```

--------------------------------

### Changelog Versioning Example: Minor Version Bump

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/RELEASING.md

Shows how to handle version updates in the changelog when the current development version is `cardano-ledger-core-1.2.4.0`, indicating a minor version bump.

```markdown
* If the current version is set to `cardano-ledger-core-1.2.4.0`. That means there was at
  most a minor version bump and currently released version is
  `cardano-ledger-core-1.2.3.x`. But your changes are breaking so you increase it even
  further to `cardano-ledger-core-1.3.0.0`
```

--------------------------------

### Run Specific Shelley Golden Tests with Environment Variable

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/CONTRIBUTING.md

Alternatively, set the TASTY_PATTERN environment variable to filter tests. This example runs the golden tests for the Shelley ledger.

```shell
TASTY_PATTERN=golden cabal test cardano-ledger-shelley-test
```

--------------------------------

### Splitting Token Bundle: Part 2

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/doc/explanations/token-bundles.md

Represents the second part of a split token bundle, TB_ExamplePart2, containing the remaining tokens from the original bundle.

```default
{ 
        NFLPlayerCardsPolicyID {
                (SomeOtherNFLPlayerCard, 1),
                (YetAnotherNFLPlayerCard, 1)}

        RushConcertPolicyID {
                (Tickets, 300),
                (VIPTickets, 30)}
}
```

--------------------------------

### Analyze Block Validation with Profiling

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/CONTRIBUTING.md

Run db-analyser to analyze block validation for a specified number of blocks, starting from a particular slot, and generate profiling data. The output file will be db-analyser.prof.

```bash
cabal run db-analyser -- --db <PATH_TO_NODE>/cardano-node/state-node-mainnet/db-mainnet/ --minimum-block-validation cardano --configByron mainnet-byron-genesis.json --configShelley mainnet-shelley-genesis.json --configAlonzo mainnet-alonzo-genesis.json --only-immutable-db --analyse-from 45288084 --num-blocks-to-process 1000 --trace-ledger +RTS -pj -l-agu -RTS
```

--------------------------------

### Create Snapshot with db-analyser

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/CONTRIBUTING.md

Use the db-analyser tool to create a snapshot of the ledger database at a specific slot for profiling. Ensure you have the mainnet config files downloaded.

```bash
cabal run db-analyser -- --db ~/io/cardano-node/state-node-mainnet/db-mainnet/ --minimum-block-validation cardano --configByron mainnet-byron-genesis.json --configShelley mainnet-shelley-genesis.json --nonce 1a3be38bcbb7911969283716ad7aa550250226b76a61fc51cc9a9a35d9276d81 --configAlonzo mainnet-alonzo-genesis.json --only-immutable-db --store-ledger 45288084
```

--------------------------------

### Run Memory Benchmark

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/libs/ledger-state/README.md

Executes the memory benchmark for the ledger-state tool, outputting results to a text file. Requires pre-generated state and DB files.

```shell
$ cabal build ledger-state:memory
$ cabal bench ledger-state:memory -v0 \
    --benchmark-option="--new-epoch-state-cbor=${CARDANO_DATA}/new-epoch-state.bin" \
    --benchmark-option="--epoch-state-cbor=${CARDANO_DATA}/epoch-state.bin" \
    --benchmark-option="--sqlite-db=${CARDANO_DATA}/epoch-state.sqlite" | tee ledger-state:memory.txt
```

--------------------------------

### Generate Allegra Era Ledger State and Transaction

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/libs/cardano-ledger-test/bench/resources/DESCRIPTION.md

Generates Allegra era ledger state and transaction for benchmarking transaction application. Requires setup within the cardano-ledger-shelley-test cabal repl.

```haskell
:set -XTypeApplications

import Data.Proxy

import Cardano.Binary
import Control.State.Transition.Trace
import Control.State.Transition.Trace.Generator.QuickCheck
import qualified Data.ByteString as BS
import Cardano.Ledger.Shelley.Rules.Ledger
import Cardano.Ledger.Shelley
import Test.Cardano.Ledger.Shelley.ConcreteCryptoTypes

import Test.Cardano.Ledger.Shelley.Utils
import Test.Cardano.Ledger.Shelley.Generator.Presets
import Test.Cardano.Ledger.Shelley.Generator.Trace.Ledger ()
import Test.Cardano.Ledger.Shelley.Generator.ShelleyEraGen ()
import Cardano.Ledger.Shelley.PParams (PParams'(..))
import Test.QuickCheck (generate)

import Test.Cardano.Ledger.Shelley.Generator.Trace.Ledger

import Cardano.Ledger.Allegra
import Test.Cardano.Ledger.AllegraEraGen ()


let ge = genEnv (Proxy @(AllegraEra C_Crypto))
initLs <- generate $ mkGenesisLedgerState @([LedgerPredicateFailure (AllegraEra C_Crypto)]) ge undefined
tr <- generate $ traceFromInitState @(LEDGER (AllegraEra C_Crypto)) testGlobals 20 ge (Just $ \_ -> pure initLs)

let sst = last $ sourceSignalTargets tr
BS.writeFile "/tmp/0_ledgerstate.cbor" $ serialize' (source sst)
BS.writeFile "/tmp/0_tx.cbor" $ serialize' (signal sst)
```

--------------------------------

### Develop with GHC 8.10 Compatibility

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/CONTRIBUTING.md

Use this command to enter a Nix development shell with GHC 8.10.7, which is necessary for maintaining compatibility during the transition to GHC 9.x. This pattern can be used for other supported GHC versions as well.

```bash
nix develop .#ghc8107
```

--------------------------------

### Generate Shelley Era Ledger State and Transaction

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/libs/cardano-ledger-test/bench/resources/DESCRIPTION.md

Generates Shelley era ledger state and transaction for benchmarking transaction application. Requires setup within the cardano-ledger-shelley-test cabal repl.

```haskell
:set -XTypeApplications

import Data.Proxy

import Cardano.Binary
import Control.State.Transition.Trace
import Control.State.Transition.Trace.Generator.QuickCheck
import qualified Data.ByteString as BS
import Cardano.Ledger.Shelley.Rules.Ledger
import Cardano.Ledger.Shelley
import Test.Cardano.Ledger.Shelley.ConcreteCryptoTypes

import Test.Cardano.Ledger.Shelley.Utils
import Test.Cardano.Ledger.Shelley.Generator.Presets
import Test.Cardano.Ledger.Shelley.Generator.Trace.Ledger ()
import Test.Cardano.Ledger.Shelley.Generator.ShelleyEraGen ()
import Cardano.Ledger.Shelley.PParams (PParams'(..))

import Test.QuickCheck (generate)

import Test.Cardano.Ledger.Shelley.Generator.Trace.Ledger

let ge = genEnv (Proxy @(ShelleyEra C_Crypto))
initLs <- generate $ mkGenesisLedgerState @([LedgerPredicateFailure (ShelleyEra C_Crypto)]) ge undefined
tr <- generate $ traceFromInitState @(LEDGER (ShelleyEra C_Crypto)) testGlobals 20 ge (Just $ \_ -> pure initLs)

let sst = last $ sourceSignalTargets tr
BS.writeFile "/tmp/0_ledgerstate.cbor" $ serialize' (source sst)
BS.writeFile "/tmp/0_tx.cbor" $ serialize' (signal sst)
```

--------------------------------

### Enable Ledger Events with applyBlockOpts

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/docs/LedgerEvents.md

Configure the ledger API to return events by setting the event policy to EPReturn. This incurs a performance cost but is useful for understanding ledger state changes.

```haskell
applyBlockOpts :: ApplySTSOpts -> Block -> LedgerState -> (LedgerState, [LedgerEvent])
applyBlockOpts opts blk lstate = 
  let asoEvents = AsoEvents { eventPolicy = EPReturn }
      opts' = opts { asoEvents = asoEvents }
  in applyBlockOpts opts' blk lstate
```

--------------------------------

### Run Complex Byron Update Mechanism Tests

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/CONTRIBUTING.md

Execute complex test patterns using awk-like syntax with the -p flag. This example targets Byron update mechanism tests that classify traces.

```shell
cabal test byron-spec-ledger:test:byron-spec-ledger-test --test-options "-p \"$1 ~ /Ledger/ && $2 ~ /Update/ && $3 ~ /classified/\""
```

--------------------------------

### Nix Configuration for NixOS

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/README.md

Add this configuration to your /etc/nixos/configuration.nix file to set up Nix caches and experimental features for faster builds.

```nix
nix.settings = {
  experimental-features = [ "nix-command" "flakes" ];
  substituters = [
    "https://cache.nixos.org"
    "https://cache.iog.io"
  ];
  trusted-public-keys = [
    "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ="
  ];
};

```

--------------------------------

### Nix Development Environment and Foliage Build

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/REVISIONING.md

Enters a Nix development shell and rebuilds the package repository using `foliage`. This step is performed after adding package revisions to ensure the repository is up-to-date.

```bash
nix develop --command bash -c "foliage build -j 0 --write-metadata"

```

--------------------------------

### Illustrative Reward Update Creation Function

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/docs/reward-calculation/HowRewardCalculationWorks.md

This function demonstrates the three phases of reward calculation (start, pulse, complete) and the recursive nature of the pulsing phase. It is primarily for illustration and testing, not directly used in the rules.

```haskell
-- | To create a reward update, run all 3 phases
--   This function is not used in the rules, so it ignores RewardEvents
--   but it illustrates the three phases and the looping behavior of the second phase
--   through a recursive call. It is also used in some tests.
createRUpd ::
  forall era.
  (EraGov era, EraCertState era) =>
  EpochSize ->
  BlocksMade ->
  EpochState era ->
  Coin ->
  ActiveSlotCoeff ->
  NonZero Word64 ->
  ShelleyBase RewardUpdate
createRUpd slotsPerEpoch blocksmade epstate maxSupply asc secparam = do
  let step1 = startStep slotsPerEpoch blocksmade epstate maxSupply asc secparam
  (step2, _event) <- pulseStep step1
  case step2 of
    Complete r -> pure r
    Pulsing rewsnap pulser -> fst <$> completeRupd (Pulsing rewsnap pulser)
```

--------------------------------

### Enter Nix Development Shell

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/eras/byron/ledger/impl/cddl-spec/README.md

Enter a Nix development shell that includes the `cuddle` tool, allowing you to use it for CDDL operations.

```shell
$ nix develop

```

--------------------------------

### Build Haskell Source with Nix (No Caching)

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/CONTRIBUTING.md

Builds the Haskell source code from the formal ledger specifications repository using Nix without Agda caching. Returns a path to the Nix store for use as an absolute path.

```shell
nix-build -A hs-src
```

--------------------------------

### Enter Nix Shell with Ruby Tools

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/eras/byron/ledger/impl/cddl-spec/README.md

Enter a Nix shell that includes the Ruby-based tools for CBOR generation and validation. Note that these tools are not compatible with Cardano eras after Babbage.

```shell
$ nix shell nixpkgs#{cddl,cbor-diag}

```

--------------------------------

### Splitting Token Bundle: Part 1

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/doc/explanations/token-bundles.md

Represents the first part of a split token bundle, TB_Example_Part1, containing a subset of the original tokens.

```default
{ 
        NFLPlayerCardsPolicyID {
                (SomeNFLPlayerCard, 1)}

        RushConcertPolicyID {
                (Tickets, 200),
                (VIPTickets, 20)}
}
```

--------------------------------

### Rebuild Repository with Foliage and Nix

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/REVISIONING.md

After adding revisions and modifying `.cabal` files, use `foliage` to rebuild the repository metadata, then use `nix build` with overrides to re-validate the packages. This step confirms if the added revisions resolve the build issues.

```bash
nix develop --command bash -c "foliage build -j 0 --write-metadata"
```

```bash
nix build --override-input CHaP path:/home/user/cardano-haskell-packages/_repo \
'.#"ghc96/cardano-ledger-allegra/1.3.0.0"' \
'.#"ghc96/cardano-ledger-alonzo/1.6.0.0"' \
'.#"ghc96/cardano-ledger-alonzo-test/1.2.0.0"' \
'.#"ghc96/cardano-ledger-babbage/1.6.0.0"' \
'.#"ghc96/byron-spec-chain/1.0.0.2"' \
'.#"ghc96/byron-spec-ledger/1.0.0.2"' \
'.#"ghc96/cardano-ledger-byron/1.0.0.4"' \
'.#"ghc96/cardano-crypto-wrapper/1.5.1.1"' \
'.#"ghc96/cardano-ledger-conway/1.12.0.0"' \
'.#"ghc96/cardano-ledger-mary/1.5.0.0"' \
'.#"ghc96/cardano-ledger-shelley/1.9.0.0"' \
'.#"ghc96/cardano-ledger-shelley-test/1.3.0.1"' \
'.#"ghc96/cardano-ledger-shelley-ma-test/1.2.1.6"' \
'.#"ghc96/cardano-ledger-api/1.8.0.0"' \
'.#"ghc96/cardano-ledger-core/1.10.0.0"' \
'.#"ghc96/cardano-ledger-binary/1.3.0.0"' \
'.#"ghc96/cardano-protocol-tpraos/1.1.0.0"' \
'.#"ghc96/non-integral/1.0.0.0"' \
'.#"ghc96/small-steps/1.0.1.0"' \
'.#"ghc96/cardano-data/1.2.0.0"' \
'.#"ghc96/vector-map/1.1.0.0"
```

--------------------------------

### Run Complete Conformance Test Suite

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/CONTRIBUTING.md

Execute the full suite of conformance tests against the Agda formal ledger specification. Ensure you are in the nix develop shell and have updated cabal packages.

```shell
nix develop
cabal update
cabal test cardano-ledger-conformance
```

--------------------------------

### Alternative Nix Shell for Profiling

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/HowToProfileLedger.md

Use this command to enter a Nix development shell with profiling enabled using an alternative compiler version.

```bash
nix develop .#ghc8107.profiling
```

--------------------------------

### Cabal Command to Build with Profiling

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/HowToProfileLedger.md

Command to build the project with profiling enabled.

```bash
cabal build --enable-profiling
```

--------------------------------

### Run Shelley Tests with Streaming Details

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/CONTRIBUTING.md

Run the Cardano Ledger Shelley era tests with the `--test-show-details=streaming` option. This provides detailed output of test execution, which is helpful for debugging.

```shell
cabal test cardano-ledger-shelley-test --test-show-details=streaming
```

--------------------------------

### Download and Use Git FSck Skiplist for Cloning

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/README.md

Download the `.git-fsck-skiplist` file and use it with `git clone` to bypass fsck errors. This is useful when `transfer.fsckObjects` is enabled globally.

```shell
$ curl -sSLO https://raw.githubusercontent.com/IntersectMBO/cardano-ledger/refs/heads/master/.git-fsck-skiplist
$ git clone -c fetch.fsck.skipList=.git-fsck-skiplist ...
...
$ rm .git-fsck-skiplist
```

--------------------------------

### Initial Cabal Build Command

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/REVISIONING.md

Updates Cabal package indexes and attempts to build a list of specified Cardano ledger packages. This command may fail if package revisions are needed.

```bash
cabal update
cabal build \
cardano-ledger-allegra \
cardano-ledger-alonzo \
cardano-ledger-alonzo-test \
cardano-ledger-babbage \
byron-spec-chain \
byron-spec-ledger \
cardano-ledger-byron \
cardano-crypto-wrapper \
cardano-ledger-conway \
cardano-ledger-mary \
cardano-ledger-shelley \
cardano-ledger-shelley-test \
cardano-ledger-shelley-ma-test \
cardano-ledger-api \
cardano-ledger-core \
cardano-ledger-binary \
cardano-protocol-tpraos \
non-integral \
small-steps \
cardano-data \
vector-map

```

--------------------------------

### Cabal Project Configuration

Source: https://github.com/intersectmbo/cardano-ledger/blob/master/REVISIONING.md

Defines a local package repository and lists packages to be built. Ensure the repository URL points to your built package repository.

```cabal
-- Give it a different name to avoid cabal confusing it with the
-- real CHaP
repository cardano-haskell-packages-local
  -- Point this to the *built* repository
  url: file:/home/user/cardano-haskell-packages/_repo
  secure: True
  -- You can skip the root-keys field

packages:
  releasing.cabal
-- Add all the packages you want to try building
extra-packages:
  cardano-ledger-allegra-1.3.0.0,
  cardano-ledger-alonzo-1.6.0.0,
  cardano-ledger-alonzo-test-1.2.0.0,
  cardano-ledger-babbage-1.6.0.0,
  byron-spec-chain-1.0.0.2,
  byron-spec-ledger-1.0.0.2,
  cardano-ledger-byron-1.0.0.4,
  cardano-crypto-wrapper-1.5.1.1,
  cardano-ledger-conway-1.12.0.0,
  cardano-ledger-mary-1.5.0.0,
  cardano-ledger-shelley-1.9.0.0,
  cardano-ledger-shelley-test-1.3.0.1,
  cardano-ledger-shelley-ma-test-1.2.1.6,
  cardano-ledger-api-1.8.0.0,
  cardano-ledger-core-1.10.0.0,
  cardano-ledger-binary-1.3.0.0,
  cardano-protocol-tpraos-1.1.0.0,
  non-integral-1.0.0.0,
  small-steps-1.0.1.0,
  cardano-data-1.2.0.0,
  vector-map-1.1.0.0

```