{
 "number": 35229,
 "repo": "bitcoin/bitcoin",
 "url": "https://github.com/bitcoin/bitcoin/pull/35229",
 "title": "refactor: Use CBlockIndex parameters as reference",
 "author": "optout21",
 "author_association": "CONTRIBUTOR",
 "created_at": "2026-05-07T07:11:44Z",
 "updated_at": "2026-09-17T02:03:06Z",
 "age_days": 133,
 "draft": false,
 "labels": [
  "Refactoring"
 ],
 "milestone": null,
 "base": "master",
 "head_sha": "a1ed86a7e66c4f13dc58fab71982eba3340602e0",
 "head_ref": "2605-block-param-ref",
 "head_repo": "optout21/bitcoin",
 "head_history": [
  {
   "t": "2026-05-07T07:17:11Z",
   "sha": "dfe62214070408e699067598309b779c1ed1214d"
  },
  {
   "t": "2026-05-20T11:15:26Z",
   "sha": "ed44574efd38d4b7815ab96ae6f68f8b02dee88a"
  },
  {
   "t": "2026-05-20T11:29:14Z",
   "sha": "52d0091f417d4ad8b5b6242b611daef162e02923"
  },
  {
   "t": "2026-05-20T11:31:57Z",
   "sha": "a9a2eb8dabe79bf0c369476745124f65ae288654"
  },
  {
   "t": "2026-05-20T11:33:21Z",
   "sha": "82fdd038cfe379c0dbdfda37e3504f97f8e21564"
  },
  {
   "t": "2026-05-26T09:18:37Z",
   "sha": "c6160bc2be3270501b645fe005dc7b69ed70ca15"
  },
  {
   "t": "2026-05-26T10:14:53Z",
   "sha": "a1ed86a7e66c4f13dc58fab71982eba3340602e0"
  }
 ],
 "additions": 78,
 "deletions": 68,
 "changed_files": 12,
 "commit_count": 7,
 "size_bucket": "M",
 "mergeable_state": "clean",
 "bot": {
  "drahtbot": {
   "present": true,
   "reviews": {
    "concept_ack": [
     {
      "login": "stickies-v",
      "url": "https://github.com/bitcoin/bitcoin/pull/35229#pullrequestreview-4242099645"
     },
     {
      "login": "musaHaruna",
      "url": "https://github.com/bitcoin/bitcoin/pull/35229#pullrequestreview-4318505356"
     },
     {
      "login": "w0xlt",
      "url": "https://github.com/bitcoin/bitcoin/pull/35229#issuecomment-4700259476"
     }
    ]
   },
   "conflicts": [
    {
     "number": 36244,
     "title": "validation, net: Process blocks asynchronously and reduce cs_main contention",
     "author": "w0xlt"
    },
    {
     "number": 35837,
     "title": "rpc: fail scanblocks when block filter range is unavailable",
     "author": "MicSm"
    }
   ]
  }
 },
 "acks_parsed": {
  "stickies-v": {
   "kind": "concept_ack",
   "hash": null,
   "t": "2026-05-07T07:52:42Z",
   "stale": false
  },
  "musaHaruna": {
   "kind": "concept_ack",
   "hash": null,
   "t": "2026-05-19T11:36:09Z",
   "stale": false
  },
  "w0xlt": {
   "kind": "concept_ack",
   "hash": null,
   "t": "2026-06-14T00:47:18Z",
   "stale": false
  }
 },
 "acks_tally": {
  "ack": 0,
  "stale_ack": 0,
  "concept_ack": 3,
  "approach_ack": 0,
  "nack": 0,
  "concept_nack": 0,
  "approach_nack": 0
 },
 "reviews": {
  "approved": 0,
  "changes_requested": 0,
  "distinct_reviewers": [
   "maflcko",
   "musaHaruna",
   "stickies-v",
   "w0xlt"
  ]
 },
 "signals": {
  "needs_rebase": false,
  "ci_failed": false,
  "mergeable_state": "clean",
  "last_author_activity": "2026-05-27T06:42:27Z",
  "last_reviewer_activity": "2026-06-14T00:47:18Z",
  "last_reviewer": "w0xlt",
  "author_silent_days": 113,
  "waiting_on_author_days": 95,
  "days_since_update": 0
 },
 "refs": {
  "mentioned": [
   34440
  ],
  "depends_on": [],
  "fixes": [],
  "linked_issues": [],
  "references": [
   {
    "number": 34440,
    "type": "pull",
    "state": "closed",
    "merged": true,
    "merged_at": "2026-04-22",
    "title": "refactor: Change CChain methods to use references, add tests"
   }
  ],
  "conflicts": [
   36244,
   35837
  ]
 },
 "stack": {
  "shares_commits_with": [],
  "based_on": [],
  "base_for": []
 },
 "review_paths": [
  "src/chain.cpp",
  "src/chain.h",
  "src/index/base.cpp",
  "src/net_processing.cpp"
 ],
 "body": "This is a janitorial refactor, a continuation of #34440. Input method parameters of type `const CBlockIndex*` are changed to reference `const CBlockIndex&` in some places where it makes no sense to call with a nullptr.\n\nMotivation: slight improvement in code quality, maintainability and robustness.\n- more explicit representation of the non-null input invariant\n- less chance of nullptr-access error with future code changes\n- more explicit checks at call sites for the non-null input invariant.\n\nThe following methods are affected:\n- `LastCommonAncestor()` in chain.h\n- `PeerManagerImpl::FindNextBlocks()` (net_processing.cpp)\n- `PeerManagerImpl::TryDownloadingHistoricalBlocks()` (net_processing.cpp)\n- `BlockFilterIndex::LookupFilterRange()`, `BlockFilterIndex::LookupFilterHashRange()` (blockfilterindex.h), and `LookupRange()` in blockfilterindex.cpp\n- `BaseIndex::ProcessBlock()` (base.h)\n\nGeneral guidelines:\n- When a method has an input of type `const CBlockIndex*`, and by contract it cannot be nullptr, change it to `const CBlockIndex&`. The reference type is an implicit documentation of the nun-nullptr invariant.\n- When calling a method with reference parameter, ensure that it cannot be nullptr (it is often derived from a pointer), by/because:\n  - explicit prior check and error handling\n  - an assert/Assert/Assume\n  - itself being a non-nullptr invariant input\n  - it is being an output from a method with no-nullptr output invariant\n- For local variables, use reference types whenever possible, for non-nullptr references\n- For technical reasons pointers are still used even in some non-nullptr cases:\n  - containers/variables that can staty unitialized initially\n  - containers that need `reserve()`\n  - using reference type in `std::set` would result in some copy constructor calls\n  - `std::optional` cannot hold a reference type",
 "commits": [
  {
   "sha": "1c3d6b2c96c77f3933a5b5030f98fe8d940d5ec2",
   "date": "2026-05-20T10:33:34Z",
   "message": "refactor: In LastCommonAncestor, change CBlockIndex input to reference"
  },
  {
   "sha": "63c9b996f4d657d3e9e12a126f38fe8ce6c06a88",
   "date": "2026-05-20T10:33:36Z",
   "message": "refactor: In FindNextBlocks, change CBlockIndex input to reference"
  },
  {
   "sha": "cec59ef3b6c3ff661835fdffd256c6dcbeda9c6a",
   "date": "2026-05-26T08:59:57Z",
   "message": "refactor: Assert and comments to ensure vBlocks never contains null"
  },
  {
   "sha": "555e7e32e2dabe33816d21548b127a9a913e3e63",
   "date": "2026-05-26T08:59:58Z",
   "message": "refactor: In TryDownloadingHistoricalBlocks, change CBlockIndex input to reference"
  },
  {
   "sha": "91e1110aaef6d32e5218eb5d011d486d105c4599",
   "date": "2026-05-26T08:59:58Z",
   "message": "refactor: In LookupX methods, change CBlockIndex input to reference\n\nMethods affected: BlockFilterIndex::LookupFilterRange, BlockFilterIndex::LookupFilterHashRange,\nand LookupRange, in blockfilterindex."
  },
  {
   "sha": "b7cc8b99ee64870c603ab9d7d7d763917a886de9",
   "date": "2026-05-26T08:59:58Z",
   "message": "refactor: In ProcessBlock change CBlockIndex input to reference"
  },
  {
   "sha": "a1ed86a7e66c4f13dc58fab71982eba3340602e0",
   "date": "2026-05-26T10:14:43Z",
   "message": "refactor: Store reference_wrapper items within CChain class\n\nIn the `vChain` internal array of `CChain` class, store items as\n`std::reference_wrapper<CBlockIndex>`, instead of `CBlockIndex*` pointers.\nThis gives a better guarantee that the entries are not null.\nThe APIs returning pointers are not changed.\nNote that the entries are not const references, due to the need to update\nduring validation."
  }
 ],
 "timeline": [
  {
   "t": "2026-05-07T07:17:11Z",
   "kind": "force_push",
   "who": "optout21",
   "commit": "dfe62214070408e699067598309b779c1ed1214d"
  },
  {
   "t": "2026-05-07T07:52:15Z",
   "kind": "review_comment",
   "who": "stickies-v",
   "assoc": "MEMBER",
   "path": "src/net_processing.cpp",
   "commit": "dfe62214070408e699067598309b779c1ed1214d",
   "in_reply_to": null,
   "text": "nit: developer notes prefer camel_case while you're touching this"
  },
  {
   "t": "2026-05-07T07:52:42Z",
   "kind": "review",
   "who": "stickies-v",
   "assoc": "MEMBER",
   "state": "COMMENTED",
   "commit": "dfe62214070408e699067598309b779c1ed1214d",
   "text": "Concept ACK"
  },
  {
   "t": "2026-05-19T11:36:09Z",
   "kind": "review",
   "who": "musaHaruna",
   "assoc": "CONTRIBUTOR",
   "state": "COMMENTED",
   "commit": "dfe62214070408e699067598309b779c1ed1214d",
   "text": "Concept ACK.\n\nRefactor makes sense to me. Changing parameters from const `CBlockIndex*` to `const CBlockIndex&` where `nullptr` is not a valid state improves clarity and gives stronger compile-time guarantees around non-nullability by making the invariant explicit."
  },
  {
   "t": "2026-05-19T11:37:34Z",
   "kind": "review_comment",
   "who": "musaHaruna",
   "assoc": "CONTRIBUTOR",
   "path": "src/chain.h",
   "commit": "dfe62214070408e699067598309b779c1ed1214d",
   "in_reply_to": null,
   "text": "Nit: We can make this comment a bit more concise and technically precise.\n\nRight now it mentions `reserve`, but the ultimate underlying constraint is simply that `std::vector` fundamentally cannot hold references entirely. We can strip out the mention of the specific method and focus purely on the core safety invariant and the language rule.\n\n```suggestion\n    std::vector<CBlockIndex*> vChain;  // Pointers, never nullptr (std::vector cannot hold references)"
  },
  {
   "t": "2026-05-19T11:44:24Z",
   "kind": "review_comment",
   "who": "musaHaruna",
   "assoc": "CONTRIBUTOR",
   "path": "src/index/base.cpp",
   "commit": "a1ed86a7e66c4f13dc58fab71982eba3340602e0",
   "in_reply_to": null,
   "text": "I think we can explicitly pass the default `nullptr` with an inline comment here to match the codebase convention.\n\n```suggestion\n      if (!ProcessBlock(*pindex, /*block_data=*/nullptr)) return; // error logged internally"
  },
  {
   "t": "2026-05-19T11:49:38Z",
   "kind": "review_comment",
   "who": "maflcko",
   "assoc": "MEMBER",
   "path": "src/chain.cpp",
   "commit": "dfe62214070408e699067598309b779c1ed1214d",
   "in_reply_to": null,
   "text": "As explained previously, this seems confusing, see https://github.com/bitcoin/bitcoin/pull/34440#discussion_r3085393412"
  },
  {
   "t": "2026-05-19T11:50:39Z",
   "kind": "review_comment",
   "who": "maflcko",
   "assoc": "MEMBER",
   "path": "src/chain.h",
   "commit": "dfe62214070408e699067598309b779c1ed1214d",
   "in_reply_to": 3265944761,
   "text": "If the code-typing overhead of `.get()` is not too much, why not just use std::reference_wrapper, which enforces everything at compile-time without any runtime overhead and does not rely on a code comment?"
  },
  {
   "t": "2026-05-20T10:16:46Z",
   "kind": "review_comment",
   "who": "optout21",
   "assoc": "CONTRIBUTOR",
   "path": "src/net_processing.cpp",
   "commit": "dfe62214070408e699067598309b779c1ed1214d",
   "in_reply_to": 3199781654,
   "text": "Done."
  },
  {
   "t": "2026-05-20T10:18:07Z",
   "kind": "review_comment",
   "who": "optout21",
   "assoc": "CONTRIBUTOR",
   "path": "src/index/base.cpp",
   "commit": "a1ed86a7e66c4f13dc58fab71982eba3340602e0",
   "in_reply_to": 3265981655,
   "text": "This is not related to this PR, plus I don't see why to explicitly pass an optional parameters, so not taking this."
  },
  {
   "t": "2026-05-20T10:27:08Z",
   "kind": "review_comment",
   "who": "optout21",
   "assoc": "CONTRIBUTOR",
   "path": "src/chain.cpp",
   "commit": "dfe62214070408e699067598309b779c1ed1214d",
   "in_reply_to": 3266011274,
   "text": "Indeed, thanks for the reminder! I wanted to have here something to \"code-show\" the return-is-not-nullptr assumption. I've double-checked the usages (call sites), and this can't happen -- all chain segments must have the same genesis. Therefore I've changed it to `Assert`. Similarly changed one other introduced `Assume` to `Assert` in `net_processing.cpp`."
  },
  {
   "t": "2026-05-20T11:11:58Z",
   "kind": "review_comment",
   "who": "optout21",
   "assoc": "CONTRIBUTOR",
   "path": "src/chain.h",
   "commit": "dfe62214070408e699067598309b779c1ed1214d",
   "in_reply_to": 3265944761,
   "text": "@musaHaruna , @maflcko : I was incorrect here, what I meant is that if `reference_wrapper`'s are used, then `resize()` has a problem (not `reserve()`!), because it would call the default constructor, and `CBlockIndex` does not have one. But I realized now that this can be solved (by passing an instance to resize).\nSo what I did:\n- Simplified the comment, as suggested, to only \"Pointers, never nullptr\"\n- I tried using `reference_wrapper` locally in `PeerManagerImpl::FindNextBlocks()`. I think the `get()` is not a big inconvenience, and the zero memory and runtime overhead is important. In there the resize sets them all to a `(*nullptr)` initially, which kind of defies the purpose, but at least the intent is clear. I put this in a separate commit.\n\nI may reconsider keeping the `reference_wrapper` commit or not, pending review.\nI will also consider using `reference_wrapper` in the `CChain` class member vector, which is a riskier change."
  },
  {
   "t": "2026-05-20T11:15:03Z",
   "kind": "review",
   "who": "optout21",
   "assoc": "CONTRIBUTOR",
   "state": "COMMENTED",
   "commit": "dfe62214070408e699067598309b779c1ed1214d",
   "text": "Did changes, following recent reviews. Thanks for the reviews!\nWhat's changed:\n- Change of Assume() to more appropriate Assert() (2 places).\n- Inside `PeerManagerImpl::FindNextBlocks()`, for the `vToFetch` vector, use `std::reference_wrapper<const CBlockIndex>` instead of pointers ([new commit!](https://github.com/bitcoin/bitcoin/pull/35229/changes/063e705c5c3945477869bea035b181440bc4ac2f))\n- Some comment adjustments.\n- Some minor renaming of touched variable/parameters.\n\n`git range-diff dfe62214070408e699067598309b779c1ed1214d...ed44574efd38d4b7815ab96ae6f68f8b02dee88a`"
  },
  {
   "t": "2026-05-20T11:15:26Z",
   "kind": "force_push",
   "who": "optout21",
   "commit": "ed44574efd38d4b7815ab96ae6f68f8b02dee88a"
  },
  {
   "t": "2026-05-20T11:29:14Z",
   "kind": "force_push",
   "who": "optout21",
   "commit": "52d0091f417d4ad8b5b6242b611daef162e02923"
  },
  {
   "t": "2026-05-20T11:31:57Z",
   "kind": "force_push",
   "who": "optout21",
   "commit": "a9a2eb8dabe79bf0c369476745124f65ae288654"
  },
  {
   "t": "2026-05-20T11:33:21Z",
   "kind": "force_push",
   "who": "optout21",
   "commit": "82fdd038cfe379c0dbdfda37e3504f97f8e21564"
  },
  {
   "t": "2026-05-20T11:37:27Z",
   "kind": "comment",
   "who": "optout21",
   "assoc": "CONTRIBUTOR",
   "text": "Pushed compile fix: initializing the `reference_wrapper` with `std::ref(*(CBlockIndex*)nullptr)` gave a build error on MacOS (but not locally). Now it's filled with the `index_walk` input parameter as a placeholder.\n\n```\ngit range-diff dfe62214070408e699067598309b779c1ed1214d...82fdd038cfe379c0dbdfda37e3504f97f8e21564\ngit range-diff ed44574efd38d4b7815ab96ae6f68f8b02dee88a...82fdd038cfe379c0dbdfda37e3504f97f8e21564\ngit range-diff dfe62214070408e699067598309b779c1ed1214d...ed44574efd38d4b7815ab96ae6f68f8b02dee88a\n```"
  },
  {
   "t": "2026-05-26T09:18:37Z",
   "kind": "force_push",
   "who": "optout21",
   "commit": "c6160bc2be3270501b645fe005dc7b69ed70ca15"
  },
  {
   "t": "2026-05-26T09:18:48Z",
   "kind": "comment",
   "who": "optout21",
   "assoc": "CONTRIBUTOR",
   "text": "Performed changes:\n\n- Reverted last addition of storing `reference_wrapper`'s inside `PeerManagerImpl::FindNextBlocks()`. That's an internal, local usage, so there is not much benefit of this change there, hence I reverted it.\n- Did change `CChain::vChain` array to store `std::reference_wrapper<CBlockIndex>` items instead of pointers ([new commit](https://github.com/bitcoin/bitcoin/pull/35229/changes/a1ed86a7e66c4f13dc58fab71982eba3340602e0)). This is to better show and ensure that entries are never null. The interfaces returning pointers are not changed.\n\n`git range-diff 82fdd038cfe379c0dbdfda37e3504f97f8e21564...a1ed86a7e66c4f13dc58fab71982eba3340602e0`"
  },
  {
   "t": "2026-05-26T10:14:53Z",
   "kind": "force_push",
   "who": "optout21",
   "commit": "a1ed86a7e66c4f13dc58fab71982eba3340602e0"
  },
  {
   "t": "2026-05-27T06:42:27Z",
   "kind": "comment",
   "who": "optout21",
   "assoc": "CONTRIBUTOR",
   "text": "There was an unrelated CI failure, but on the second try all CI builds passed.\nThe failure was in \"Windows, ucrt, test cross-built\":\n```\nError: fatal: unable to access 'https://github.com/bitcoin/bitcoin/': The requested URL returned error: 403\n```\nseemingly an intermittent infrastructure issue, most likely unrelated to this PR.\n\nhttps://github.com/bitcoin/bitcoin/actions/runs/26446276736/job/77856772060?pr=35229"
  },
  {
   "t": "2026-06-14T00:47:18Z",
   "kind": "comment",
   "who": "w0xlt",
   "assoc": "CONTRIBUTOR",
   "text": "Concept ACK"
  }
 ],
 "labels_log": [
  {
   "t": "2026-05-07T07:11:50Z",
   "action": "labeled",
   "label": "Refactoring",
   "who": "DrahtBot"
  },
  {
   "t": "2026-05-07T07:17:42Z",
   "action": "labeled",
   "label": "CI failed",
   "who": "DrahtBot"
  },
  {
   "t": "2026-05-07T08:15:44Z",
   "action": "unlabeled",
   "label": "CI failed",
   "who": "DrahtBot"
  },
  {
   "t": "2026-05-20T11:30:32Z",
   "action": "labeled",
   "label": "CI failed",
   "who": "DrahtBot"
  },
  {
   "t": "2026-05-20T12:26:14Z",
   "action": "unlabeled",
   "label": "CI failed",
   "who": "DrahtBot"
  },
  {
   "t": "2026-05-26T10:15:22Z",
   "action": "labeled",
   "label": "CI failed",
   "who": "DrahtBot"
  },
  {
   "t": "2026-05-26T23:35:53Z",
   "action": "unlabeled",
   "label": "CI failed",
   "who": "DrahtBot"
  }
 ],
 "state_log": [
  {
   "t": "2026-05-09T06:48:57Z",
   "kind": "ready_for_review",
   "who": "optout21"
  },
  {
   "t": "2026-05-26T09:09:28Z",
   "kind": "convert_to_draft",
   "who": "optout21"
  },
  {
   "t": "2026-05-26T10:11:47Z",
   "kind": "ready_for_review",
   "who": "optout21"
  },
  {
   "t": "2026-05-26T22:03:52Z",
   "kind": "closed",
   "who": "optout21"
  },
  {
   "t": "2026-05-26T22:03:56Z",
   "kind": "reopened",
   "who": "optout21"
  }
 ],
 "text_chars": 7840,
 "text_tokens_estimate": 1960,
 "changed_paths": [
  "src/chain.cpp",
  "src/chain.h",
  "src/index/base.cpp",
  "src/index/base.h",
  "src/index/blockfilterindex.cpp",
  "src/index/blockfilterindex.h",
  "src/net_processing.cpp",
  "src/node/interfaces.cpp",
  "src/rpc/blockchain.cpp",
  "src/test/blockfilter_index_tests.cpp",
  "src/test/chain_tests.cpp",
  "src/validation.cpp"
 ],
 "files": [
  {
   "path": "src/chain.cpp",
   "add": 14,
   "del": 11
  },
  {
   "path": "src/chain.h",
   "add": 9,
   "del": 6
  },
  {
   "path": "src/index/base.cpp",
   "add": 9,
   "del": 9
  },
  {
   "path": "src/index/base.h",
   "add": 1,
   "del": 1
  },
  {
   "path": "src/index/blockfilterindex.cpp",
   "add": 8,
   "del": 8
  },
  {
   "path": "src/index/blockfilterindex.h",
   "add": 2,
   "del": 2
  },
  {
   "path": "src/net_processing.cpp",
   "add": 24,
   "del": 20
  },
  {
   "path": "src/node/interfaces.cpp",
   "add": 1,
   "del": 1
  },
  {
   "path": "src/rpc/blockchain.cpp",
   "add": 2,
   "del": 1
  },
  {
   "path": "src/test/blockfilter_index_tests.cpp",
   "add": 6,
   "del": 6
  },
  {
   "path": "src/test/chain_tests.cpp",
   "add": 1,
   "del": 1
  },
  {
   "path": "src/validation.cpp",
   "add": 1,
   "del": 2
  }
 ],
 "test_lines": 14,
 "git": {
  "head": "a1ed86a7e66c4f13dc58fab71982eba3340602e0",
  "head_matches_backup": true,
  "base": "7c84a2bdb1625a759d2e8597d5c48415d4d9bfeb",
  "commits": [
   {
    "sha": "1c3d6b2c96",
    "subject": "refactor: In LastCommonAncestor, change CBlockIndex input to reference",
    "files": 6,
    "add": 19,
    "del": 16
   },
   {
    "sha": "63c9b996f4",
    "subject": "refactor: In FindNextBlocks, change CBlockIndex input to reference",
    "files": 1,
    "add": 7,
    "del": 6
   },
   {
    "sha": "cec59ef3b6",
    "subject": "refactor: Assert and comments to ensure vBlocks never contains null",
    "files": 1,
    "add": 6,
    "del": 1
   },
   {
    "sha": "555e7e32e2",
    "subject": "refactor: In TryDownloadingHistoricalBlocks, change CBlockIndex input to reference",
    "files": 1,
    "add": 5,
    "del": 8
   },
   {
    "sha": "91e1110aae",
    "subject": "refactor: In LookupX methods, change CBlockIndex input to reference",
    "files": 5,
    "add": 21,
    "del": 19
   },
   {
    "sha": "b7cc8b99ee",
    "subject": "refactor: In ProcessBlock change CBlockIndex input to reference",
    "files": 2,
    "add": 10,
    "del": 10
   },
   {
    "sha": "a1ed86a7e6",
    "subject": "refactor: Store reference_wrapper items within CChain class",
    "files": 2,
    "add": 13,
    "del": 11
   }
  ],
  "patch_truncated": false
 },
 "input_hash": "0d3790ccfb3e2819",
 "extracted_at": "2026-09-17T16:15:31+00:00"
}