{
 "number": 33820,
 "repo": "bitcoin/bitcoin",
 "url": "https://github.com/bitcoin/bitcoin/pull/33820",
 "title": "kernel: trim Chain interface",
 "author": "stickies-v",
 "author_association": "CONTRIBUTOR",
 "created_at": "2025-11-07T16:50:57Z",
 "updated_at": "2025-11-10T10:35:30Z",
 "age_days": 313,
 "draft": false,
 "labels": [
  "Validation"
 ],
 "milestone": null,
 "base": "master",
 "head_sha": "f4b3ba18d9bf3e7c2c55a98f3c3d98129a1fa6e2",
 "head_ref": "2025-11/kernel-trim-chain-interface",
 "head_repo": "stickies-v/bitcoin",
 "head_history": [],
 "additions": 2,
 "deletions": 33,
 "changed_files": 3,
 "commit_count": 2,
 "size_bucket": "S",
 "mergeable_state": "unknown",
 "bot": {
  "drahtbot": {
   "present": true,
   "reviews": {
    "ack": [
     {
      "login": "yuvicc",
      "url": "https://github.com/bitcoin/bitcoin/pull/33820#pullrequestreview-3438421965"
     }
    ],
    "concept_ack": [
     {
      "login": "TheCharlatan",
      "url": "https://github.com/bitcoin/bitcoin/pull/33820#pullrequestreview-3438917702"
     }
    ]
   },
   "conflicts": []
  }
 },
 "acks_parsed": {
  "yuvicc": {
   "kind": "ack",
   "hash": "f4b3ba18d9bf3e7c2c55a98f3c3d98129a1fa6e2",
   "t": "2025-11-08T14:32:27Z",
   "stale": false
  },
  "TheCharlatan": {
   "kind": "concept_ack",
   "hash": null,
   "t": "2025-11-08T22:24:23Z",
   "stale": false
  }
 },
 "acks_tally": {
  "ack": 1,
  "stale_ack": 0,
  "concept_ack": 1,
  "approach_ack": 0,
  "nack": 0,
  "concept_nack": 0,
  "approach_nack": 0
 },
 "reviews": {
  "approved": 0,
  "changes_requested": 0,
  "distinct_reviewers": [
   "TheCharlatan",
   "maflcko",
   "yuvicc"
  ]
 },
 "signals": {
  "needs_rebase": false,
  "ci_failed": false,
  "mergeable_state": "unknown",
  "last_author_activity": "2025-11-10T10:29:46Z",
  "last_reviewer_activity": "2025-11-10T10:35:30Z",
  "last_reviewer": "TheCharlatan",
  "author_silent_days": 311,
  "waiting_on_author_days": 311,
  "days_since_update": 311
 },
 "refs": {
  "mentioned": [],
  "depends_on": [],
  "fixes": [],
  "linked_issues": [],
  "references": [],
  "conflicts": []
 },
 "stack": {
  "shares_commits_with": [],
  "based_on": [],
  "base_for": []
 },
 "review_paths": [
  "src/kernel/bitcoinkernel_wrapper.h"
 ],
 "body": "Removes `btck_chain_get_genesis` and `btck_chain_get_tip`.\n\nThey are trivially replaced with `btck_chain_get_by_height` (as indicated in the updated `bitcoinkernel_wrapper.h`), so I think it makes sense to trim the interface.\n\nFor `btck_chain_get_tip`: on `master` we don't provide any guarantees that the returned block index still corresponds to the actual tip, so the extra call doesn't seem like a regression to me.",
 "commits": [
  {
   "sha": "737b6566f6710e5bf2c35966ad1c417788bf0635",
   "date": "2025-11-07T16:46:10Z",
   "message": "kernel: remove btck_chain_get_genesis\n\nIt is equivalent to calling btck_chain_get_by_height(0)."
  },
  {
   "sha": "f4b3ba18d9bf3e7c2c55a98f3c3d98129a1fa6e2",
   "date": "2025-11-07T16:46:10Z",
   "message": "kernel: remove btck_chain_get_tip\n\nIt is equivalent to calling btck_chain_get_by_height with the\nheight obtained from btck_chain_get_height. In neither case do we\nprovide guarantees that the returned block index still corresponds\nto the actual tip."
  }
 ],
 "timeline": [
  {
   "t": "2025-11-08T14:32:27Z",
   "kind": "review",
   "who": "yuvicc",
   "assoc": "CONTRIBUTOR",
   "state": "COMMENTED",
   "commit": "f4b3ba18d9bf3e7c2c55a98f3c3d98129a1fa6e2",
   "text": "ACK f4b3ba18d9bf3e7c2c55a98f3c3d98129a1fa6e2\n\nThis makes sense to me."
  },
  {
   "t": "2025-11-08T22:23:03Z",
   "kind": "review_comment",
   "who": "TheCharlatan",
   "assoc": "CONTRIBUTOR",
   "path": "src/kernel/bitcoinkernel_wrapper.h",
   "commit": "f4b3ba18d9bf3e7c2c55a98f3c3d98129a1fa6e2",
   "in_reply_to": null,
   "text": "I wonder if we should even keep these methods now. The previous calls to tip and genesis were at least thread safe (which these are no longer). I agree that it is not worth keeping them just for the sake of it, but also not sure if they still provide utility here."
  },
  {
   "t": "2025-11-08T22:24:23Z",
   "kind": "review",
   "who": "TheCharlatan",
   "assoc": "CONTRIBUTOR",
   "state": "COMMENTED",
   "commit": "f4b3ba18d9bf3e7c2c55a98f3c3d98129a1fa6e2",
   "text": "Concept ACK\n\nThese were introduced before we had a dedicated iterator for traversing the chain. At this point, their benefit (thread safety) is kind of marginal."
  },
  {
   "t": "2025-11-10T09:38:38Z",
   "kind": "review_comment",
   "who": "stickies-v",
   "assoc": "CONTRIBUTOR",
   "path": "src/kernel/bitcoinkernel_wrapper.h",
   "commit": "f4b3ba18d9bf3e7c2c55a98f3c3d98129a1fa6e2",
   "in_reply_to": 2507308573,
   "text": "[quoted text omitted]\n\nWith previous, do you mean master? I'm not sure how the current calls are not thread safe? These are read-only calls without side effects? And both in master and this PR, the caller has no guarantees that the returned tip is indeed the tip because cs_main isn't exposed (regardless of threads)?\n\n[quoted text omitted]\nI agree, but I want to generalize that even more. I think `Range` objects should be the only `public` interface for their contents. Duplicated getter and count methods on the parent seem confusing and unnecessary, and are best made `private` imo. I'm taking that approach with py-bitcoinkernel and I think it works well. But I think given the added scope that's better suited for a separate PR, which I'll push out soon."
  },
  {
   "t": "2025-11-10T09:45:15Z",
   "kind": "review_comment",
   "who": "maflcko",
   "assoc": "MEMBER",
   "path": "src/kernel/bitcoinkernel_wrapper.h",
   "commit": "f4b3ba18d9bf3e7c2c55a98f3c3d98129a1fa6e2",
   "in_reply_to": 2507308573,
   "text": "[quoted text omitted]\n\nI think there could be a rare and theoretical race where the function does not return any tip, but rather throws `std::runtime_error(\"No entry in the chain at the provided height\");` when the height is re-orged out to a lower more-work height. But this is mostly an edge case."
  },
  {
   "t": "2025-11-10T10:29:46Z",
   "kind": "review_comment",
   "who": "stickies-v",
   "assoc": "CONTRIBUTOR",
   "path": "src/kernel/bitcoinkernel_wrapper.h",
   "commit": "f4b3ba18d9bf3e7c2c55a98f3c3d98129a1fa6e2",
   "in_reply_to": 2507308573,
   "text": "I hadn't thought of the reduced-height reorg scenario, thanks for that. Reorg-safety in general is still an unsolved problem for the public interface, and this is another case of that.\n\nNote: the problem you report already exists for objects based on the  `Range` class whenever `size()` depends on chain length, such as for `Chain::Entries` with `Chain::Entries::back()` being able to throw a `std::runtime_error`."
  },
  {
   "t": "2025-11-10T10:35:30Z",
   "kind": "review_comment",
   "who": "TheCharlatan",
   "assoc": "CONTRIBUTOR",
   "path": "src/kernel/bitcoinkernel_wrapper.h",
   "commit": "f4b3ba18d9bf3e7c2c55a98f3c3d98129a1fa6e2",
   "in_reply_to": 2507308573,
   "text": "Yes, I was merely mentioning it, because the `Tip` and `Genesis` methods in current master at least provided a bit better integrity. I don't think this is important at all though. External callers should provide synchronization for this. So the two calls should just be removed imo."
  }
 ],
 "labels_log": [
  {
   "t": "2025-11-07T16:51:10Z",
   "action": "labeled",
   "label": "Validation",
   "who": "DrahtBot"
  }
 ],
 "state_log": [],
 "text_chars": 3050,
 "text_tokens_estimate": 762,
 "changed_paths": [],
 "files": [],
 "test_lines": 0,
 "git": {
  "head": "66978a1a95379a2fe5d41032682dedfaddc99db9",
  "head_matches_backup": false,
  "base": "66978a1a95379a2fe5d41032682dedfaddc99db9",
  "commits": [],
  "patch_truncated": false
 },
 "input_hash": "fbb2400e330e296f",
 "extracted_at": "2026-09-17T16:15:31+00:00"
}