v2

Co-authored-by: Radosław Kapka <rkapka@wp.pl>

CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to this project will be documented in this file.
 
 The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
 
+## [v6.1.3](https://github.com/prysmaticlabs/prysm/compare/v6.1.2...v6.1.3) - 2025-10-20
+
+This release has several important beacon API and p2p fixes.
+
+### Added
+
+- Add Grandine to P2P known agents. (Useful for metrics). [[PR]](https://github.com/prysmaticlabs/prysm/pull/15829)
+- Delegate sszInfo HashTreeRoot to FastSSZ-generated implementations via SSZObject, enabling roots calculation for generated types while avoiding duplicate logic. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15805)
+- SSZ-QL: Use `fastssz`'s `SizeSSZ` method for calculating the size of `Container` type. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15864)
+- SSZ-QL: Access n-th element in `List`/`Vector`. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15767)
+
+### Changed
+
+- Do not verify block data when calculating rewards. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15819)
+- Process pending attestations after pending blocks are cleared. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15824)
+- updated web3signer to 25.9.1. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15832)
+- Gracefully handle submit blind block returning 502 errors. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15848)
+- Improve returning individual message errors from Beacon API. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15835)
+- SSZ-QL: Clarify `Size` method with more sophisticated `SSZType`s. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15864)
+
+### Fixed
+
+- Use service context and continue on slasher attestation errors (#15803). [[PR]](https://github.com/prysmaticlabs/prysm/pull/15803)
+- block event probably shouldn't be sent on certain block processing failures, now sends only on successing processing Block is NON-CANONICAL, Block IS CANONICAL but getFCUArgs FAILS, and Full success. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15814)
+- Fixed web3signer e2e, issues caused due to a regression on old fork support. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15832)
+- Do not mark blocks as invalid from ErrNotDescendantOfFinalized. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15846)
+- Fixed [#15812](https://github.com/OffchainLabs/prysm/issues/15812): Gossip attestation validation incorrectly rejecting attestations that arrive before their referenced blocks. Previously, attestations were saved to the pending queue but immediately rejected by forkchoice validation, causing "not descendant of finalized checkpoint" errors. Now attestations for missing blocks return `ValidationIgnore` without error, allowing them to be properly processed when their blocks arrive. This eliminates false positive rejections and prevents potential incorrect peer downscoring during network congestion. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15840)
+- Mark the block as invalid if it has an invalid signature. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15847)
+- Display error messages from the server verbatim when they are not encoded as `application/json`. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15860)
+- `HasAtLeastOneIndex`: Check the index is not too high. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15865)
+- Fix `/eth/v1/beacon/blob_sidecars/` beacon API is the fulu fork epoch is set to the far future epoch. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15867)
+- `dataColumnSidecarsByRangeRPCHandler`: Gracefully close the stream if no data to return. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15866)
+- `VerifyDataColumnSidecar`: Check if there is no too many commitments. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15859)
+- `WithDataColumnRetentionEpochs`: Use `dataColumnRetentionEpoch` instead of `blobColumnRetentionEpoch`. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15872)
+- Mark epoch transition correctly on new head events. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15871)
+- reject committee index >= committees_per_slot in unaggregated attestation validation. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15855)
+- Decreased attestation gossip validation batch deadline to 5ms. [[PR]](https://github.com/prysmaticlabs/prysm/pull/15882)
+
 ## [v6.1.2](https://github.com/prysmaticlabs/prysm/compare/v6.1.1...v6.1.2) - 2025-10-10
 
 This release has several important fixes to improve Prysm's peering, stability, and attestation inclusion on mainnet and all testnets. All node operators are encouraged to update to this release as soon as practical for the best mainnet performance.
@@ -3759,4 +3797,4 @@ There are no security updates in this release.
 
 # Older than v2.0.0
 
-For changelog history for releases older than v2.0.0, please refer to https://github.com/prysmaticlabs/prysm/releases
+For changelog history for releases older than v2.0.0, please refer to https://github.com/prysmaticlabs/prysm/releases

beacon-chain/rpc/prysm/v1alpha1/validator/proposer.go

@@ -229,7 +229,7 @@ func (vs *Server) BuildBlockParallel(ctx context.Context, sBlk interfaces.Signed
 		sBlk.SetVoluntaryExits(vs.getExits(head, sBlk.Block().Slot()))
 
 		// Set sync aggregate. New in Altair.
-		vs.setSyncAggregate(ctx, sBlk)
+		vs.setSyncAggregate(ctx, sBlk, head)
 
 		// Set bls to execution change. New in Capella.
 		vs.setBlsToExecData(sBlk, head)

beacon-chain/rpc/prysm/v1alpha1/validator/proposer_altair.go

@@ -5,6 +5,7 @@ import (
 	"context"
 
 	"github.com/OffchainLabs/prysm/v6/beacon-chain/core/helpers"
+	"github.com/OffchainLabs/prysm/v6/beacon-chain/state"
 	"github.com/OffchainLabs/prysm/v6/config/params"
 	"github.com/OffchainLabs/prysm/v6/consensus-types/interfaces"
 	"github.com/OffchainLabs/prysm/v6/consensus-types/primitives"
@@ -20,12 +21,12 @@ import (
 	"github.com/prysmaticlabs/go-bitfield"
 )
 
-func (vs *Server) setSyncAggregate(ctx context.Context, blk interfaces.SignedBeaconBlock) {
+func (vs *Server) setSyncAggregate(ctx context.Context, blk interfaces.SignedBeaconBlock, headState state.BeaconState) {
 	if blk.Version() < version.Altair {
 		return
 	}
 
-	syncAggregate, err := vs.getSyncAggregate(ctx, slots.PrevSlot(blk.Block().Slot()), blk.Block().ParentRoot())
+	syncAggregate, err := vs.getSyncAggregate(ctx, slots.PrevSlot(blk.Block().Slot()), blk.Block().ParentRoot(), headState)
 	if err != nil {
 		log.WithError(err).Error("Could not get sync aggregate")
 		emptySig := [96]byte{0xC0}
@@ -47,7 +48,7 @@ func (vs *Server) setSyncAggregate(ctx context.Context, blk interfaces.SignedBea
 
 // getSyncAggregate retrieves the sync contributions from the pool to construct the sync aggregate object.
 // The contributions are filtered based on matching of the input root and slot then profitability.
-func (vs *Server) getSyncAggregate(ctx context.Context, slot primitives.Slot, root [32]byte) (*ethpb.SyncAggregate, error) {
+func (vs *Server) getSyncAggregate(ctx context.Context, slot primitives.Slot, root [32]byte, headState state.BeaconState) (*ethpb.SyncAggregate, error) {
 	_, span := trace.StartSpan(ctx, "ProposerServer.getSyncAggregate")
 	defer span.End()
 
@@ -62,7 +63,7 @@ func (vs *Server) getSyncAggregate(ctx context.Context, slot primitives.Slot, ro
 	// Contributions have to match the input root
 	proposerContributions := proposerSyncContributions(poolContributions).filterByBlockRoot(root)
 
-	aggregatedContributions, err := vs.aggregatedSyncCommitteeMessages(ctx, slot, root, poolContributions)
+	aggregatedContributions, err := vs.aggregatedSyncCommitteeMessages(ctx, slot, root, poolContributions, headState)
 	if err != nil {
 		return nil, errors.Wrap(err, "could not get aggregated sync committee messages")
 	}
@@ -123,6 +124,7 @@ func (vs *Server) aggregatedSyncCommitteeMessages(
 	slot primitives.Slot,
 	root [32]byte,
 	poolContributions []*ethpb.SyncCommitteeContribution,
+	st state.BeaconState,
 ) ([]*ethpb.SyncCommitteeContribution, error) {
 	subcommitteeCount := params.BeaconConfig().SyncCommitteeSubnetCount
 	subcommitteeSize := params.BeaconConfig().SyncCommitteeSize / subcommitteeCount
@@ -146,10 +148,7 @@ func (vs *Server) aggregatedSyncCommitteeMessages(
 			messageSigs = append(messageSigs, msg.Signature)
 		}
 	}
-	st, err := vs.HeadFetcher.HeadState(ctx)
-	if err != nil {
-		return nil, errors.Wrap(err, "could not get head state")
-	}
+
 	positions, err := helpers.CurrentPeriodPositions(st, messageIndices)
 	if err != nil {
 		return nil, errors.Wrap(err, "could not get sync committee positions")

beacon-chain/rpc/prysm/v1alpha1/validator/proposer_altair_test.go

@@ -9,6 +9,7 @@ import (
 	mockSync "github.com/OffchainLabs/prysm/v6/beacon-chain/sync/initial-sync/testing"
 	"github.com/OffchainLabs/prysm/v6/config/params"
 	"github.com/OffchainLabs/prysm/v6/consensus-types/blocks"
+	"github.com/OffchainLabs/prysm/v6/consensus-types/primitives"
 	"github.com/OffchainLabs/prysm/v6/crypto/bls"
 	"github.com/OffchainLabs/prysm/v6/encoding/bytesutil"
 	ethpb "github.com/OffchainLabs/prysm/v6/proto/prysm/v1alpha1"
@@ -51,15 +52,15 @@ func TestProposer_GetSyncAggregate_OK(t *testing.T) {
 		require.NoError(t, proposerServer.SyncCommitteePool.SaveSyncCommitteeContribution(cont))
 	}
 
-	aggregate, err := proposerServer.getSyncAggregate(t.Context(), 1, bytesutil.ToBytes32(conts[0].BlockRoot))
+	aggregate, err := proposerServer.getSyncAggregate(t.Context(), 1, bytesutil.ToBytes32(conts[0].BlockRoot), st)
 	require.NoError(t, err)
 	require.DeepEqual(t, bitfield.Bitvector32{0xf, 0xf, 0xf, 0xf}, aggregate.SyncCommitteeBits)
 
-	aggregate, err = proposerServer.getSyncAggregate(t.Context(), 2, bytesutil.ToBytes32(conts[0].BlockRoot))
+	aggregate, err = proposerServer.getSyncAggregate(t.Context(), 2, bytesutil.ToBytes32(conts[0].BlockRoot), st)
 	require.NoError(t, err)
 	require.DeepEqual(t, bitfield.Bitvector32{0xaa, 0xaa, 0xaa, 0xaa}, aggregate.SyncCommitteeBits)
 
-	aggregate, err = proposerServer.getSyncAggregate(t.Context(), 3, bytesutil.ToBytes32(conts[0].BlockRoot))
+	aggregate, err = proposerServer.getSyncAggregate(t.Context(), 3, bytesutil.ToBytes32(conts[0].BlockRoot), st)
 	require.NoError(t, err)
 	require.DeepEqual(t, bitfield.NewBitvector32(), aggregate.SyncCommitteeBits)
 }
@@ -68,7 +69,7 @@ func TestServer_SetSyncAggregate_EmptyCase(t *testing.T) {
 	b, err := blocks.NewSignedBeaconBlock(util.NewBeaconBlockAltair())
 	require.NoError(t, err)
 	s := &Server{} // Sever is not initialized with sync committee pool.
-	s.setSyncAggregate(t.Context(), b)
+	s.setSyncAggregate(t.Context(), b, nil)
 	agg, err := b.Block().Body().SyncAggregate()
 	require.NoError(t, err)
 
@@ -138,7 +139,7 @@ func TestProposer_GetSyncAggregate_IncludesSyncCommitteeMessages(t *testing.T) {
 	}
 
 	// The final sync aggregates must have indexes [0,1,2,3] set for both subcommittees
-	sa, err := proposerServer.getSyncAggregate(t.Context(), 1, r)
+	sa, err := proposerServer.getSyncAggregate(t.Context(), 1, r, st)
 	require.NoError(t, err)
 	assert.Equal(t, true, sa.SyncCommitteeBits.BitAt(0))
 	assert.Equal(t, true, sa.SyncCommitteeBits.BitAt(1))
@@ -194,8 +195,99 @@ func Test_aggregatedSyncCommitteeMessages_NoIntersectionWithPoolContributions(t
 		BlockRoot:         r[:],
 	}
 
-	aggregated, err := proposerServer.aggregatedSyncCommitteeMessages(t.Context(), 1, r, []*ethpb.SyncCommitteeContribution{cont})
+	aggregated, err := proposerServer.aggregatedSyncCommitteeMessages(t.Context(), 1, r, []*ethpb.SyncCommitteeContribution{cont}, st)
 	require.NoError(t, err)
 	require.Equal(t, 1, len(aggregated))
 	assert.Equal(t, false, aggregated[0].AggregationBits.BitAt(3))
 }
+
+func TestGetSyncAggregate_CorrectStateAtSyncCommitteePeriodBoundary(t *testing.T) {
+	helpers.ClearCache()
+	syncPeriodBoundaryEpoch := primitives.Epoch(274176) // Real epoch from the bug report
+	slotsPerEpoch := params.BeaconConfig().SlotsPerEpoch
+
+	preEpochState, keys := util.DeterministicGenesisStateAltair(t, 100)
+	require.NoError(t, preEpochState.SetSlot(primitives.Slot(syncPeriodBoundaryEpoch)*slotsPerEpoch-1)) // Last slot of previous epoch
+
+	postEpochState := preEpochState.Copy()
+	require.NoError(t, postEpochState.SetSlot(primitives.Slot(syncPeriodBoundaryEpoch)*slotsPerEpoch+2)) // After 2 missed slots
+
+	oldCommittee := &ethpb.SyncCommittee{
+		Pubkeys: make([][]byte, params.BeaconConfig().SyncCommitteeSize),
+	}
+	newCommittee := &ethpb.SyncCommittee{
+		Pubkeys: make([][]byte, params.BeaconConfig().SyncCommitteeSize),
+	}
+
+	for i := 0; i < int(params.BeaconConfig().SyncCommitteeSize); i++ {
+		if i < len(keys) {
+			oldCommittee.Pubkeys[i] = keys[i%len(keys)].PublicKey().Marshal()
+			// Use different keys for new committee to simulate rotation
+			newCommittee.Pubkeys[i] = keys[(i+10)%len(keys)].PublicKey().Marshal()
+		}
+	}
+
+	require.NoError(t, preEpochState.SetCurrentSyncCommittee(oldCommittee))
+	require.NoError(t, postEpochState.SetCurrentSyncCommittee(newCommittee))
+
+	mockChainService := &chainmock.ChainService{
+		State: postEpochState,
+	}
+
+	proposerServer := &Server{
+		HeadFetcher:       mockChainService,
+		SyncChecker:       &mockSync.Sync{IsSyncing: false},
+		SyncCommitteePool: synccommittee.NewStore(),
+	}
+
+	slot := primitives.Slot(syncPeriodBoundaryEpoch)*slotsPerEpoch + 1 // First slot of new epoch
+	blockRoot := [32]byte{0x01, 0x02, 0x03}
+
+	msg1 := &ethpb.SyncCommitteeMessage{
+		Slot:           slot,
+		BlockRoot:      blockRoot[:],
+		ValidatorIndex: 0, // This validator is in position 0 of OLD committee
+		Signature:      bls.NewAggregateSignature().Marshal(),
+	}
+	msg2 := &ethpb.SyncCommitteeMessage{
+		Slot:           slot,
+		BlockRoot:      blockRoot[:],
+		ValidatorIndex: 1, // This validator is in position 1 of OLD committee
+		Signature:      bls.NewAggregateSignature().Marshal(),
+	}
+
+	require.NoError(t, proposerServer.SyncCommitteePool.SaveSyncCommitteeMessage(msg1))
+	require.NoError(t, proposerServer.SyncCommitteePool.SaveSyncCommitteeMessage(msg2))
+
+	aggregateWrongState, err := proposerServer.getSyncAggregate(t.Context(), slot, blockRoot, postEpochState)
+	require.NoError(t, err)
+
+	aggregateCorrectState, err := proposerServer.getSyncAggregate(t.Context(), slot, blockRoot, preEpochState)
+	require.NoError(t, err)
+
+	wrongStateBits := bitfield.Bitlist(aggregateWrongState.SyncCommitteeBits)
+	correctStateBits := bitfield.Bitlist(aggregateCorrectState.SyncCommitteeBits)
+
+	wrongStateHasValidators := false
+	correctStateHasValidators := false
+
+	for i := 0; i < len(wrongStateBits); i++ {
+		if wrongStateBits[i] != 0 {
+			wrongStateHasValidators = true
+			break
+		}
+	}
+
+	for i := 0; i < len(correctStateBits); i++ {
+		if correctStateBits[i] != 0 {
+			correctStateHasValidators = true
+			break
+		}
+	}
+
+	assert.Equal(t, true, correctStateHasValidators, "Correct state should include validators that sent messages")
+	assert.Equal(t, false, wrongStateHasValidators, "Wrong state should not find validators in incorrect sync committee")
+
+	t.Logf("Wrong state aggregate bits: %x (has validators: %v)", wrongStateBits, wrongStateHasValidators)
+	t.Logf("Correct state aggregate bits: %x (has validators: %v)", correctStateBits, correctStateHasValidators)
+}

changelog/Galoretka_feature-slasher-feed-use-service-ctx.md

@@ -1,3 +0,0 @@
-### Fixed
-
-- Use service context and continue on slasher attestation errors (#15803).

changelog/bastin_add-log-control-doc.md

@@ -0,0 +1,3 @@
+### Ignored
+
+- Add log control design doc.

changelog/fernantho_ssz-ql-use-fastssz-generated-functions.md

@@ -1,3 +0,0 @@
-### Added
-
-- Delegate sszInfo HashTreeRoot to FastSSZ-generated implementations via SSZObject, enabling roots calculation for generated types while avoiding duplicate logic.

changelog/james-prysm_cleanup-process-aggregate.md

@@ -1,3 +0,0 @@
-### Ignored
-
-- Small code changes for reusability and readability to processAggregate.

changelog/james-prysm_fix-block-event.md

@@ -1,3 +0,0 @@
-### Fixed
-
-- block event probably shouldn't be sent on certain block processing failures, now sends only on successing processing Block is NON-CANONICAL, Block IS CANONICAL but getFCUArgs FAILS, and Full success

changelog/james-prysm_fix-web3signer-e2e.md

@@ -1,7 +0,0 @@
-### Fixed
-
-- Fixed web3signer e2e, issues caused due to a regression on old fork support
-
-### Changed
-
-- updated web3signer to 25.9.1

changelog/james-prysm_v6.1.3.md

@@ -0,0 +1,3 @@
+### Ignored
+
+- Changelog entries for v6.1.3 through v6.1.2

changelog/kasey_att-batch-5ms-deadline.md

@@ -1,2 +0,0 @@
-### Fixed
-- Decreased attestation gossip validation batch deadline to 5ms.

changelog/manu-adjust-log-levels.md

@@ -1,2 +0,0 @@
-### Ignored 
-- Data column sidecars fetch: Adjust log levels.

changelog/manu-blob-sidecars-beacon-api.md

@@ -1,2 +0,0 @@
-### Fixed 
-- Fix `/eth/v1/beacon/blob_sidecars/` beacon API is the fulu fork epoch is set to the far future epoch.

changelog/manu-check-commitment-count.md

@@ -1,2 +0,0 @@
-### Fixed 
-- `VerifyDataColumnSidecar`: Check if there is no too many commitments.

changelog/manu-data-column-retention-period.md

@@ -1,2 +0,0 @@
-### Fixed 
-- `WithDataColumnRetentionEpochs`: Use `dataColumnRetentionEpoch` instead of `blobColumnRetentionEpoch`.

changelog/manu-gracefully-close-stream.md

@@ -1,2 +0,0 @@
-### Fixed 
-- `dataColumnSidecarsByRangeRPCHandler`: Gracefully close the stream if no data to return.

changelog/manu-grandine-known-agents.md

@@ -1,2 +0,0 @@
-### Added 
-- Add Grandine to P2P known agents. (Useful for metrics)

changelog/manu-has-at-least-one-index.md

@@ -1,2 +0,0 @@
-### Fixed 
-- `HasAtLeastOneIndex`: Check the index is not too high.

changelog/marcopolo_push-nxynxywxtlpo.md

@@ -1,2 +0,0 @@
-### Ignored
-- Fix (unreleased) bug where the preallocated slice for KZG Proofs was 48x bigger than it needed to be.

changelog/phrwlk_fix-attestation-committee-index-bound.md

@@ -1,3 +0,0 @@
-### Fixed
-
-- reject committee index >= committees_per_slot in unaggregated attestation validation

changelog/potuz_fix_head_event.md

@@ -1,3 +0,0 @@
-### Fixed
-
-- Mark epoch transition correctly on new head events

changelog/potuz_invalid_not_descendant.md

@@ -1,3 +0,0 @@
-### Fixed
-
-- Do not mark blocks as invalid from ErrNotDescendantOfFinalized

changelog/potuz_invalid_sig.md

@@ -1,3 +0,0 @@
-### Fixed
-
-- Mark the block as invalid if it has an invalid signature. 

changelog/potuz_redundant_check.md

@@ -1,3 +0,0 @@
-### Ignored
-
-- Remove redundant check for genesis root at startup. 

changelog/pvl-v6.1.2.md

@@ -1,3 +0,0 @@
-### Ignored
-
-- Changelog entries for v6.1.2 through v6.0.5

changelog/radek_api-individual-failure.md

@@ -1,3 +0,0 @@
-### Changed
-
-- Improve returning individual message errors from Beacon API.

changelog/radek_read-non-json-error.md

@@ -1,3 +0,0 @@
-### Fixed
-
-- Display error messages from the server verbatim when they are not encoded as `application/json`.

changelog/radek_rewards-no-verify.md

@@ -1,3 +0,0 @@
-### Changed
-
-- Do not verify block data when calculating rewards.

changelog/satushh-gossip.md

@@ -1,3 +0,0 @@
-### Fixed
-
-- Fixed [#15812](https://github.com/OffchainLabs/prysm/issues/15812): Gossip attestation validation incorrectly rejecting attestations that arrive before their referenced blocks. Previously, attestations were saved to the pending queue but immediately rejected by forkchoice validation, causing "not descendant of finalized checkpoint" errors. Now attestations for missing blocks return `ValidationIgnore` without error, allowing them to be properly processed when their blocks arrive. This eliminates false positive rejections and prevents potential incorrect peer downscoring during network congestion.

changelog/syjn99_ssz-ql-fastssz-sizessz.md

@@ -1,7 +0,0 @@
-### Added
-
-- SSZ-QL: Use `fastssz`'s `SizeSSZ` method for calculating the size of `Container` type.
-
-### Changed
-
-- SSZ-QL: Clarify `Size` method with more sophisticated `SSZType`s.

changelog/syjn99_ssz-ql-index-accessing.md

@@ -1,3 +0,0 @@
-### Added
-
-- SSZ-QL: Access n-th element in `List`/`Vector`.

changelog/ttsao_fix-sync-aggregate-state.md

@@ -0,0 +1,3 @@
+### Fixed
+
+- Sync committee uses correct state to calculate position

changelog/ttsao_handle-relay-502-errors.md

@@ -1,3 +0,0 @@
-### Changed
-
-- Gracefully handle submit blind block returning 502 errors.

changelog/ttsao_optimize-pending-attestation-processing.md

@@ -1,3 +0,0 @@
-### Changed
-
-- Process pending attestations after pending blocks are cleared

runtime/logging/logging.md

@@ -0,0 +1,108 @@
+## Advanced Log Control in Prysm
+
+> [!WARNING]  
+> This is a work in progress. The design is not finalized, nor the implementation is complete.
+> This warning will be removed when the design and implementation are finalized.
+
+### Goals
+
+The goal of this work is to give more control over the logging system to the user. Right now the user can only control
+the global verbose level of the logs, which has some limitations. Mainly, the user does not have control over:
+
+1. Which packages are logging to the terminal. (Per-Package Visibility)
+2. What is the verbosity level for each package. (Per-Package Verbosity)
+
+We try to tackle these limitations, by providing a simple, optional mechanism to the user.
+
+### Per-Package Visibility
+
+We will offer two new config flags:
+
+1. `--log-only <comma separated path of packages>`: by providing this flag, the logs will only consist of
+   the packages that the user has mentioned. All other logs will be ignored.
+2. `--log-exclude <comma separated list of package paths>`: by providing this flag, the logs will consist of all enabled
+   logs, except the logs from packages mentioned by the user.
+
+These flags follow the inheritance model, meaning that if a package is included/excluded, all its sub-packages are also
+included/excluded. Here is an example:
+
+`--log-only beacon-chain/db,beacon-chain/p2p  --log-exclude beacon-chain/db/kv,beacon-chain/p2p/peers`
+
+In case of conflicting rules (same package mentioned in both flags), the `--log-only` flag takes precedence.
+
+These flags have nothing to do with verbosity.
+
+### Per-Package Verbosity
+
+We currently have a flag `--verbosity <trace|debug|info|warn|error>` which sets the default verbosity for all logs.
+We will introduce a new config flag `--log-vmodule value` which overrides the default verbosity for the packages
+mentioned here.
+
+An example of the flag use:
+`--log-vmodule beacon-chain/db/kv=trace,beacon-chain/p2p=debug`
+
+Any package not mentioned will take the verbosity of the provided `--verbosity` flag, or if not provided, the default
+`info` value.
+
+This flag has nothing to do with visibility.
+
+### Prerequisite
+
+We need to define a `log.go` file for every package that uses logging.
+The file should include a declaration of the `log` variable with a field `package` set to
+the full path of the package inside prysm.
+
+For example package `kv` will have this `log.go` file:
+
+```go
+package kv
+
+import "github.com/sirupsen/logrus"
+
+var log = logrus.WithField("package", "beacon-chain/db/kv")
+```
+
+This way we can filter logs based on the paths provided by the user.
+
+### Implementation
+
+We can have a script that generates the `log.go` file for every package that uses logging.
+After generating the files, we can have a CI check that ensures that every package that uses logging has this file.
+If not, devs should fix it manually by adding this file, or by running the script again.
+
+We do not need EVERY package to have this file.
+For example `testing/` or `tools/` are probably not needed.
+Here is the list of number of packages per top level folder in the project:
+
+- api – 14
+- async – 3
+- beacon-chain – 112
+- cache – 2
+- cmd – 30
+- config – 6
+- consensus-types – 13
+- container – 7
+- contracts – 2
+- crypto – 11
+- encoding – 6
+- genesis – 2
+- io – 4
+- math – 1
+- monitoring – 7
+- network – 3
+- proto – 17
+- runtime – 11
+- testing – 84
+- time – 4
+- tools – 50
+- validator – 37
+
+We can exclude some of these paths from the rule.
+
+### Improvements
+
+We can also offer additional features here:
+
+- We can let the users know that they can skip writing `beacon-chain` or `validator` in their path. We can just try for
+  those paths as well, since most logs come from these packages.
+- We could warn the user in case of conflicting rules in the visibility flags.