{
 "number": 36353,
 "input_hash": "09837e4d130928b6",
 "model": "ledger",
 "prompt_hash": null,
 "created": "2026-10-10T01:23:46+00:00",
 "result": {
  "summary": "Document in the libbitcoinkernel C API headers that `btck_Block` instances cache context-free validation results. The header comments for `btck_block_check` and `btck_chainstate_manager_process_block` now warn callers that cached checks persist across shallow copies and that a block should only be used with a single set of consensus parameters.",
  "problem": "In `libbitcoinkernel`, `btck_Block` wraps a shared `CBlock`. Once context-free checks pass under one set of consensus parameters, `CheckBlock` sets `fChecked`, causing subsequent checks or processing calls on that block (or its copies) under different parameters to skip validation and return success without warning the API consumer.",
  "card": "Documents that `btck_Block` instances cache context-free validation results in the libbitcoinkernel C API. Because `btck_Block` wraps a shared `CBlock` and sets `fChecked`, verifying a block under one set of consensus parameters causes subsequent validation under different parameters to skip checks and pass erroneously. This PR warns API consumers in header documentation to only evaluate a block against a single set of consensus parameters rather than altering validation behavior in code.",
  "evidence": [
   "PR description: 'once a block passed btck_block_check or btck_chainstate_manager_process_block, later calls on it (or on a copy) skip the checks, whatever consensus params or flags are passed. For example a regtest block that has passed once with regtest params also returns 1 from btck_block_check with mainnet params.'"
  ],
  "scope_notes": "",
  "changed_since_previous": "Switched from a code fix that created shallow unflagged copies of the block on every call to purely documentation notes in `src/kernel/bitcoinkernel.h` advising users to not reuse a block across multiple sets of consensus parameters.",
  "thread": {
   "last_event_at": "2026-10-09T15:51:53Z",
   "events": 14,
   "head_sha": "3add4efcd2af064e59678aa41748868c748f2731",
   "schema_floor": 2,
   "schema": 2
  },
  "waiting_on": [
   {
    "at": "2026-10-09",
    "id": "rc:4231979389",
    "on": "reviewer",
    "url": "https://github.com/bitcoin/bitcoin/pull/36353#discussion_r4231979389",
    "what": "alexanderwiederin and others to review updated documentation in 3add4efcd2af"
   }
  ],
  "risk": {
   "level": "low",
   "touches": [
    "docs"
   ],
   "why": "This is a documentation-only change to the libbitcoinkernel public header."
  },
  "discussion": {
   "author_status": "last statement processed 2026-10-09",
   "open_concerns": [],
   "resolved_concerns": [
    "yuvicc: assert the reason for rejection in test_kernel.cpp (fixed by FlashWayne 2026-09-30)",
    "yuvicc: document in bitcoinkernel.h that the block is not modified and earlier checks do not affect results (fixed by FlashWayne 2026-09-30)",
    "sedited: Paying a copy for every check call to protect against a scenario that should never happen is not worthwhile (fixed by FlashWayne 2026-10-08)",
    "alexanderwiederin: Narrow the description to specify that the cache only takes effect when POW and Merkle root are checked (fixed by FlashWayne 2026-10-09)",
    "alexanderwiederin: Drop the clause from btck_chainstate_manager_process_block since ProcessNewBlock sets fCheckPOW and fCheckMerkleRoot to true (fixed by FlashWayne 2026-10-09)"
   ]
  },
  "reviewability": {
   "state": "Ready",
   "label": "Ready",
   "reason": "Nothing known that would invalidate a review now."
  },
  "agreement": {
   "state": "Mild",
   "summary": "Mild: NACK from sedited not withdrawn (Paying a copy for every check call to protect against a scenario that should never happen is not worthwhile)",
   "reason": "alexanderwiederin pointed out that CheckBlock caching requires POW and Merkle root checks, and that process_block always performs both checks; the author addressed both suggestions in updates 47cb9a682b and 3add4efcd2af.",
   "evidence": [
    "yuvicc: Concept ACK \u2014 Good observation.",
    "yuvicc: ACK \u2014 The only overhead is that a block passed in a second time re-runs the context-free checks instead of returning early; for a duplicate process_block call, AcceptBlock still returns early on fAlreadyHave",
    "l0rinc: Concept ACK",
    "jcastros: ACK \u2014 tested ac8a65d939 with -DBUILD_KERNEL_LIB=ON; tests failed with parent bitcoinkernel.cpp and passed with the PR commit"
   ],
   "objections": [
    {
     "reviewer": "yuvicc",
     "association": "CONTRIBUTOR",
     "type": "suggestion",
     "kind": "correctness",
     "harm": "",
     "request": "assert the reason for rejection in test_kernel.cpp",
     "question": "",
     "text": "assert the reason for rejection in test_kernel.cpp",
     "clears_with": "answer",
     "blocking": false,
     "status": "fixed",
     "status_note": "implemented in ac8a65d939",
     "cleared": true,
     "author_replied": true,
     "others_replied": false,
     "fix_pushed": true,
     "replies": [
      "c:5906509613"
     ],
     "evidence": "2026-09-30: 'could also assert the reason for rejection'",
     "url": "https://github.com/bitcoin/bitcoin/pull/36353#discussion_r4141526992",
     "id": "rc:4141526992",
     "at": "2026-09-30",
     "status_at": "2026-09-30",
     "status_by": "FlashWayne",
     "resolution_evidence": "2026-09-30: FlashWayne: 'the signet test now also asserts BlockValidationResult::CONSENSUS'",
     "pin": null,
     "from_schema": 2
    },
    {
     "reviewer": "yuvicc",
     "association": "CONTRIBUTOR",
     "type": "suggestion",
     "kind": "interface",
     "harm": "",
     "request": "document in bitcoinkernel.h that the block is not modified and earlier checks do not affect results",
     "question": "",
     "text": "document in bitcoinkernel.h that the block is not modified and earlier checks do not affect results",
     "clears_with": "answer",
     "blocking": false,
     "status": "fixed",
     "status_note": "documentation added in ac8a65d939 and maintained in docs-only rework 54b363a291",
     "cleared": true,
     "author_replied": true,
     "others_replied": false,
     "fix_pushed": true,
     "replies": [
      "c:5906509613",
      "c:6065383919"
     ],
     "evidence": "2026-09-30: 'documenting would be useful `src/kernel/bitcoinkernel.h`, in the docs of both `btck_block_check` and `btck_chainstate_manager_process_block`'",
     "url": "https://github.com/bitcoin/bitcoin/pull/36353#discussion_r4141764396",
     "id": "rc:4141764396",
     "at": "2026-09-30",
     "status_at": "2026-09-30",
     "status_by": "FlashWayne",
     "resolution_evidence": "2026-09-30: FlashWayne: 'the note is added to the docs of btck_block_check and btck_chainstate_manager_process_block in bitcoinkernel.h'",
     "pin": null,
     "from_schema": 2
    },
    {
     "reviewer": "sedited",
     "association": "MEMBER",
     "type": "objection",
     "kind": "approach",
     "harm": "Paying a copy for every check call to protect against a scenario that should never happen is not worthwhile",
     "request": "",
     "question": "",
     "text": "Paying a copy for every check call to protect against a scenario that should never happen is not worthwhile",
     "clears_with": "change",
     "blocking": true,
     "status": "fixed",
     "status_note": "author dropped the copy and switched PR to docs only in 54b363a291",
     "cleared": true,
     "author_replied": true,
     "others_replied": false,
     "fix_pushed": true,
     "replies": [
      "c:6065383919"
     ],
     "evidence": "2026-10-08: 'Paying a copy for every check call to protect against a scenario that should never happen, does not seem worthwhile to me.'",
     "url": "https://github.com/bitcoin/bitcoin/pull/36353#issuecomment-6064504067",
     "id": "c:6064504067",
     "at": "2026-10-08",
     "status_at": "2026-10-08",
     "status_by": "FlashWayne",
     "resolution_evidence": "2026-10-08: FlashWayne: 'I dropped the copy and the tests. The PR is now a single docs commit (54b363a291, rebased on current master'",
     "pin": null,
     "from_schema": 2
    },
    {
     "reviewer": "alexanderwiederin",
     "association": "MEMBER",
     "type": "suggestion",
     "kind": "correctness",
     "harm": "",
     "request": "Narrow the description to specify that the cache only takes effect when POW and Merkle root are checked",
     "question": "",
     "text": "Narrow the description to specify that the cache only takes effect when POW and Merkle root are checked",
     "clears_with": "answer",
     "blocking": false,
     "status": "fixed",
     "status_note": "author narrowed both doc comments in 47cb9a682b",
     "cleared": true,
     "author_replied": true,
     "others_replied": false,
     "fix_pushed": true,
     "replies": [
      "c:6081039205"
     ],
     "evidence": "2026-10-09: 'I think the description is too broad. The cache only takes effect when POW and the Merkle root are checked.'",
     "url": "https://github.com/bitcoin/bitcoin/pull/36353#discussion_r4229887144",
     "id": "rc:4229887144",
     "at": "2026-10-09",
     "status_at": "2026-10-09",
     "status_by": "FlashWayne",
     "resolution_evidence": "2026-10-09: FlashWayne: 'I narrowed both doc comments accordingly in 47cb9a682b.'",
     "pin": null,
     "from_schema": 2
    },
    {
     "reviewer": "alexanderwiederin",
     "association": "MEMBER",
     "type": "suggestion",
     "kind": "correctness",
     "harm": "",
     "request": "Drop the clause from btck_chainstate_manager_process_block since ProcessNewBlock sets fCheckPOW and fCheckMerkleRoot to true",
     "question": "",
     "text": "Drop the clause from btck_chainstate_manager_process_block since ProcessNewBlock sets fCheckPOW and fCheckMerkleRoot to true",
     "clears_with": "answer",
     "blocking": false,
     "status": "fixed",
     "status_note": "author dropped the clause from process_block docs in 3add4efcd2af",
     "cleared": true,
     "author_replied": true,
     "others_replied": false,
     "fix_pushed": true,
     "replies": [
      "rc:4231979389"
     ],
     "evidence": "2026-10-09: 'You don't have to add the clause here. `ProcessNewBlock` calls `CheckBlock` with `fCheckPOW` and `fCheckMerkleRoot` set to their default `true`.'",
     "url": "https://github.com/bitcoin/bitcoin/pull/36353#discussion_r4231810698",
     "id": "rc:4231810698",
     "at": "2026-10-09",
     "status_at": "2026-10-09",
     "status_by": "FlashWayne",
     "resolution_evidence": "2026-10-09: FlashWayne: 'dropped the clause from the `process_block` docs in 3add4efcd2af'",
     "pin": null,
     "from_schema": 2
    }
   ],
   "support": [
    {
     "reviewer": "yuvicc",
     "reason": "Good observation.",
     "substantive": false,
     "verdict": "Concept ACK",
     "id": "c:5905037578",
     "url": "https://github.com/bitcoin/bitcoin/pull/36353#issuecomment-5905037578",
     "at": "2026-09-30",
     "association": "CONTRIBUTOR",
     "evidence": "none",
     "areas": []
    },
    {
     "reviewer": "yuvicc",
     "reason": "The only overhead is that a block passed in a second time re-runs the context-free checks instead of returning early; for a duplicate process_block call, AcceptBlock still returns early on fAlreadyHave",
     "substantive": true,
     "verdict": "ACK",
     "id": "r:5362379358",
     "url": "https://github.com/bitcoin/bitcoin/pull/36353#pullrequestreview-5362379358",
     "at": "2026-09-30",
     "association": "CONTRIBUTOR",
     "evidence": "read",
     "areas": [
      "src/kernel/bitcoinkernel.cpp"
     ]
    },
    {
     "reviewer": "l0rinc",
     "reason": "",
     "substantive": false,
     "verdict": "Concept ACK",
     "id": "c:5938501653",
     "url": "https://github.com/bitcoin/bitcoin/pull/36353#issuecomment-5938501653",
     "at": "2026-10-01",
     "association": "MEMBER",
     "evidence": "none",
     "areas": []
    },
    {
     "reviewer": "jcastros",
     "reason": "tested ac8a65d939 with -DBUILD_KERNEL_LIB=ON; tests failed with parent bitcoinkernel.cpp and passed with the PR commit",
     "substantive": true,
     "verdict": "ACK",
     "id": "c:5971806968",
     "url": "https://github.com/bitcoin/bitcoin/pull/36353#issuecomment-5971806968",
     "at": "2026-10-03",
     "association": "CONTRIBUTOR",
     "evidence": "tested",
     "areas": []
    }
   ],
   "participants": [
    {
     "login": "yuvicc",
     "stance": "support",
     "note": "Concept ACK and ACK; suggested asserting rejection reason and documenting kernel behavior",
     "association": "CONTRIBUTOR",
     "comments": 4,
     "first": "2026-09-30",
     "last": "2026-09-30"
    },
    {
     "login": "l0rinc",
     "stance": "support",
     "note": "Concept ACK",
     "association": "MEMBER",
     "comments": 1,
     "first": "2026-10-01",
     "last": "2026-10-01"
    },
    {
     "login": "jcastros",
     "stance": "support",
     "note": "ACK after testing against parent commit",
     "association": "CONTRIBUTOR",
     "comments": 1,
     "first": "2026-10-03",
     "last": "2026-10-03"
    },
    {
     "login": "sedited",
     "stance": "objection",
     "note": "Approach NACK on copying the block on every call; author switched to docs-only",
     "association": "MEMBER",
     "comments": 1,
     "first": "2026-10-08",
     "last": "2026-10-08"
    },
    {
     "login": "alexanderwiederin",
     "stance": "neutral",
     "note": "pointed out cache conditions and suggested refining doc phrasing",
     "association": "MEMBER",
     "comments": 2,
     "first": "2026-10-09",
     "last": "2026-10-09"
    }
   ],
   "derivation": "NACK from sedited not withdrawn (Paying a copy for every check call to protect against a scenario that should never happen is not worthwhile)",
   "model_state": null,
   "corrections": [],
   "notes": "alexanderwiederin pointed out that CheckBlock caching requires POW and Merkle root checks, and that process_block always performs both checks; the author addressed both suggestions in updates 47cb9a682b and 3add4efcd2af."
  },
  "dependencies": {
   "depends_on": [],
   "enables": []
  },
  "categories": [
   {
    "name": "kernel",
    "member": true,
    "evidence": "Changes `src/kernel/bitcoinkernel.h` to document C API block validation caching behavior.",
    "band": "P3",
    "reason_tag": "cleanup",
    "score": 0.3,
    "factors": {
     "bug_severity": 0,
     "leverage": 0,
     "performance": 0,
     "security_stability": 0,
     "user_value": 1
    },
    "rationale": "Clarifies API boundary invariants and caveats for library consumers. The comments warn callers that `btck_Block` instances cache context-free checks via internal `fChecked` flags that persist across shallow copies, preventing unexpected validation bypasses when reusing block objects across differing consensus parameters."
   },
   {
    "name": "validation",
    "member": false,
    "evidence": "Only modifies the kernel C API header comments in `src/kernel/bitcoinkernel.h` and does not touch validation code or behavior.",
    "band": "Unranked",
    "reason_tag": "cleanup",
    "score": 0.0,
    "factors": {
     "bug_severity": 0,
     "leverage": 0,
     "performance": 0,
     "security_stability": 0,
     "user_value": 1
    },
    "rationale": "Does not touch consensus or validation logic; the category explicitly excludes PRs whose primary subject is the kernel library API."
   }
  ],
  "confidence": "high",
  "uncertainties": [],
  "needs": []
 },
 "cost_usd": 0.0,
 "source": {
  "record": "2026-10-10T01:23:46+00:00",
  "code": "2026-10-10T01:25:23+00:00",
  "judgments": 2
 }
}